feat: gitlab codeowners section owner parsing (#11999)

feat: gitlab codeowners section owner parsing

Co-authored-by: daniel.mohedano <daniel.mohedano@datadoghq.com>

Author: daniel-mohedano

dd-java-agent/agent-ci-visibility/src/main/java/datadog/trace/civisibility/codeowners/CodeownersImpl.java

@@ -5,17 +5,28 @@
 import java.io.IOException;
 import java.io.Reader;
 import java.util.ArrayDeque;
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.Deque;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 public class CodeownersImpl implements Codeowners {
 
-  private final Iterable<Entry> entries;
+  // Entries grouped by section in order of appearance (the unnamed section that precedes the first
+  // header comes first). Within a section, the highest-priority (last in the file) matching entry
+  // wins and owners from every matching section are then combined.
+  private final Collection<Deque<Entry>> sections;
 
-  private CodeownersImpl(Iterable<Entry> entries) {
-    this.entries = entries;
+  private CodeownersImpl(Collection<Deque<Entry>> sections) {
+    this.sections = sections;
   }
 
   /**
@@ -25,12 +36,19 @@ private CodeownersImpl(Iterable<Entry> entries) {
   @Override
   public @Nullable Collection<String> getOwners(@Nonnull String path) {
     char[] pathCharacters = path.toCharArray();
-    for (Entry entry : entries) {
-      if (entry.getMatcher().consume(pathCharacters, 0) >= 0) {
-        return entry.getOwners();
+    Set<String> owners = null;
+    for (Deque<Entry> section : sections) {
+      for (Entry entry : section) {
+        if (entry.getMatcher().consume(pathCharacters, 0) >= 0) {
+          if (owners == null) {
+            owners = new LinkedHashSet<>();
+          }
+          owners.addAll(entry.getOwners());
+          break; // highest-priority match within a section wins
+        }
       }
     }
-    return null;
+    return owners != null ? new ArrayList<>(owners) : null;
   }
 
   @Override
@@ -39,20 +57,37 @@ public boolean exist() {
   }
 
   public static Codeowners parse(Reader r) throws IOException {
-    Deque<Entry> entries = new ArrayDeque<>();
+    Deque<Entry> defaultSection = new ArrayDeque<>();
+    Map<String, Deque<Entry>> namedSections = new LinkedHashMap<>();
+    Deque<Entry> currentSection = defaultSection;
 
     CharacterMatcher.Factory characterMatcherFactory = new CharacterMatcher.Factory();
     BufferedReader br = new BufferedReader(r);
-    String s;
-    while ((s = br.readLine()) != null) {
-      EntryBuilder entryBuilder = new EntryBuilder(characterMatcherFactory, s);
-      Entry entry = entryBuilder.parse();
+    String line;
+    // Entries without owners inherit the current section's default owners
+    Collection<String> sectionDefaultOwners = Collections.emptyList();
+    while ((line = br.readLine()) != null) {
+      EntryBuilder entryBuilder = new EntryBuilder(characterMatcherFactory, line);
+
+      SectionHeader header = entryBuilder.parseSectionHeader();
+      if (header != null) {
+        sectionDefaultOwners = header.getDefaultOwners();
+        String key = header.getName().trim().toLowerCase(Locale.ROOT);
+        currentSection = namedSections.computeIfAbsent(key, k -> new ArrayDeque<>());
+        continue;
+      }
+
+      Entry entry = entryBuilder.parse(sectionDefaultOwners);
       if (entry != null) {
-        // place last parsed entry in the beginning of the list, since it has the highest priority
-        entries.offerFirst(entry);
+        // within a section, the last entry in the file has the highest priority
+        currentSection.offerFirst(entry);
       }
     }
 
-    return new CodeownersImpl(entries);
+    // Unnamed section is evaluated first, then named sections in order of first appearance
+    List<Deque<Entry>> sections = new ArrayList<>(namedSections.size() + 1);
+    sections.add(defaultSection);
+    sections.addAll(namedSections.values());
+    return new CodeownersImpl(sections);
   }
 }

dd-java-agent/agent-ci-visibility/src/main/java/datadog/trace/civisibility/codeowners/EntryBuilder.java

@@ -12,8 +12,8 @@
 import datadog.trace.civisibility.codeowners.matcher.RangeMatcher;
 import java.util.ArrayDeque;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.Deque;
 import javax.annotation.Nullable;
 import org.slf4j.Logger;
@@ -46,29 +46,116 @@ public EntryBuilder(CharacterMatcher.Factory characterMatcherFactory, String s)
   }
 
   public @Nullable Entry parse() {
+    return parse(Collections.emptyList());
+  }
+
+  /**
+   * Parses the line as a CODEOWNERS entry: a path pattern optionally followed by one or more
+   * owners.
+   *
+   * @param sectionDefaultOwners default owners declared on the enclosing GitLab section header,
+   *     used when the entry declares no owners of its own. Pass an empty collection for entries
+   *     that do not belong to a section (e.g. GitHub CODEOWNERS files).
+   * @return the parsed entry, or {@code null} for blank lines, comments, section headers, or lines
+   *     that cannot be parsed.
+   */
+  public @Nullable Entry parse(Collection<String> sectionDefaultOwners) {
     try {
-      // skip trailing whitespace
-      while (offset < c.length && Character.isWhitespace(c[offset])) {
-        offset++;
-      }
+      skipWhitespace();
 
       if (offset == c.length // empty line
           || c[offset] == '#' // comment
-          || c[offset] == '[' // section header
-          || (c[offset] == '^'
-              && offset + 1 < c.length
-              && c[offset + 1] == '[')) { // GitLab optional section header (^[...])
+          || isSectionHeader()) { // GitLab section header (including optional '^[')
         return null;
       }
 
       Matcher matcher = parseMatcher();
       Collection<String> owners = parseOwners();
+      if (owners.isEmpty()) {
+        owners = sectionDefaultOwners;
+      }
       return new Entry(matcher, owners);
 
     } catch (Exception e) {
-      log.error("error parsing CODEOWNERS pattern: {}", Arrays.toString(c), e);
+      log.warn("Skipping malformed CODEOWNERS entry: {}", new String(c), e);
+      return null;
+    }
+  }
+
+  /**
+   * If the line is a GitLab section header, consumes it and returns the parsed {@link
+   * SectionHeader} (its name and default owners). Returns {@code null} when the line is not a
+   * section header, leaving the cursor at the start of the pattern so the line can be parsed with
+   * {@link #parse(Collection)}.
+   *
+   * <p>Supports the GitLab header syntax {@code ^[Section name][N] @owner}: an optional leading
+   * {@code ^} (optional section), a bracketed name that may contain spaces, an optional {@code [N]}
+   * required-approvals count, and trailing default owners.
+   *
+   * @see <a href="https://docs.gitlab.com/user/project/codeowners/reference/">GitLab Code Owners
+   *     reference</a>
+   */
+  public @Nullable SectionHeader parseSectionHeader() {
+    skipWhitespace();
+    if (!isSectionHeader()) {
       return null;
     }
+    if (c[offset] == '^') {
+      offset++; // consume the optional-section marker
+    }
+    offset++; // consume the opening '['
+    int nameStart = offset;
+    while (offset < c.length && c[offset] != ']') {
+      offset++; // consume the section name (which may contain spaces)
+    }
+    String name = new String(c, nameStart, offset - nameStart);
+    if (offset < c.length) {
+      offset++; // consume the closing ']'
+    }
+    // skip the optional [N] required-approvals count that may immediately follow the name
+    if (offset < c.length && c[offset] == '[') {
+      while (offset < c.length && c[offset] != ']') {
+        offset++;
+      }
+      if (offset < c.length) {
+        offset++; // consume the closing ']'
+      }
+    }
+    return new SectionHeader(name, parseOwners());
+  }
+
+  private void skipWhitespace() {
+    while (offset < c.length && Character.isWhitespace(c[offset])) {
+      offset++;
+    }
+  }
+
+  /**
+   * Determines whether the line, starting at the current cursor (with leading whitespace already
+   * skipped), is a section header. Does not move the cursor.
+   *
+   * <p>A section header begins with {@code [} — or the GitLab optional-section marker {@code ^[} —
+   * and the section name's closing {@code ]} is followed by end-of-line, whitespace, a comment
+   * ({@code #}), or the optional {@code [N]} approvals count. Requiring that trailing context
+   * distinguishes a section header from a path pattern that merely begins with a character class
+   * such as {@code [a-z]*.txt}.
+   */
+  private boolean isSectionHeader() {
+    int i = offset;
+    if (i < c.length && c[i] == '^') {
+      i++; // optional-section marker
+    }
+    if (i >= c.length || c[i] != '[') {
+      return false;
+    }
+    while (i < c.length && c[i] != ']') {
+      i++; // scan to the section name's closing ']'
+    }
+    if (i >= c.length) {
+      return false; // unterminated brackets: not a well-formed section header
+    }
+    i++; // move past ']'
+    return i >= c.length || Character.isWhitespace(c[i]) || c[i] == '[' || c[i] == '#';
   }
 
   private Matcher parseMatcher() {

dd-java-agent/agent-ci-visibility/src/main/java/datadog/trace/civisibility/codeowners/SectionHeader.java

@@ -0,0 +1,27 @@
+package datadog.trace.civisibility.codeowners;
+
+import java.util.Collection;
+
+/**
+ * A parsed GitLab CODEOWNERS section header, holding the section {@code name} (used to combine
+ * blocks that repeat a name) and the {@code defaultOwners} it declares (inherited by entries in the
+ * section that do not declare their own).
+ */
+public class SectionHeader {
+
+  private final String name;
+  private final Collection<String> defaultOwners;
+
+  public SectionHeader(String name, Collection<String> defaultOwners) {
+    this.name = name;
+    this.defaultOwners = defaultOwners;
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public Collection<String> getDefaultOwners() {
+    return defaultOwners;
+  }
+}