TeamCsvService.java

package edu.ucsb.cs156.frontiers.services;

import edu.ucsb.cs156.frontiers.entities.RosterStudent;
import edu.ucsb.cs156.frontiers.models.NameAndTeam;
import java.io.IOException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import org.apache.commons.csv.CSVFormat;
import org.apache.commons.csv.CSVPrinter;
import org.springframework.stereotype.Service;

/**
 * Builds the compact team tables that instructors traditionally produce by hand: every student's
 * name abbreviated as far as it can be while staying unique, laid out in several side-by-side
 * column pairs (e.g. "Name,Team,,Name,Team"). The name abbreviation, the column balancing and the
 * CSV writing are separate steps so that different tables (name to team, team to names) can share
 * them.
 */
@Service
public class TeamCsvService {

  /**
   * How many students are listed in each "Name,Team" column of the "by name" table in the formatted
   * teams CSV ({@link #writeFormattedTeamsCsv(Writer, List)}).
   */
  public static final int NAMES_PER_COLUMN = 24;

  /**
   * How many teams are listed in each "Team,Name" column of the "by team" table in the formatted
   * teams CSV ({@link #writeFormattedTeamsCsv(Writer, List)}).
   */
  public static final int TEAMS_PER_COLUMN = 4;

  /**
   * Converts a name to Title Case: the first letter of each word is upper case and the rest lower
   * case. A new word starts after any non-letter character, so hyphenated names and names with
   * apostrophes are handled (e.g. "MARY-JANE O'BRIEN" becomes "Mary-Jane O'Brien"). Leading and
   * trailing whitespace is removed; null becomes "".
   *
   * @param name the raw name (may be null)
   * @return the name in Title Case
   */
  public String titleCase(String name) {
    if (name == null) {
      return "";
    }
    String trimmed = name.trim();
    StringBuilder result = new StringBuilder(trimmed.length());
    boolean startOfWord = true;
    for (char c : trimmed.toCharArray()) {
      if (Character.isLetter(c)) {
        result.append(startOfWord ? Character.toUpperCase(c) : Character.toLowerCase(c));
        startOfWord = false;
      } else {
        result.append(c);
        startOfWord = true;
      }
    }
    return result.toString();
  }

  /**
   * Returns the first word of the given name: everything before the first whitespace, once leading
   * and trailing whitespace has been removed. The roster's first name field often holds a first and
   * a middle name ("Chris Edward"); we assume the first space marks the end of the first name. Null
   * becomes "".
   *
   * @param name the raw name (may be null)
   * @return the first word of the name
   */
  public String firstWord(String name) {
    if (name == null) {
      return "";
    }
    return name.trim().split("\\s+", 2)[0];
  }

  /**
   * Computes the abbreviated name and team for each student, preserving the order of the input
   * list. The first name is the first word of the roster's first name field (see {@link
   * #firstWord}), so a middle name in that field is ignored. Each name is abbreviated as far as
   * possible while remaining unique among all students:
   *
   * <ul>
   *   <li>first name only, where no other student shares that first name;
   *   <li>first name plus last initial, where that is enough to be unambiguous;
   *   <li>first name plus full last name, otherwise;
   *   <li>first name plus full last name followed by an asterisk, when another student has exactly
   *       the same first and last name (the instructor can then disambiguate by hand).
   * </ul>
   *
   * The team is the first of the student's teams, or "" if the student has no team.
   *
   * @param students the roster students, already in the desired order
   * @return one NameAndTeam per student, in the same order
   */
  public List<NameAndTeam> nameAndTeams(List<RosterStudent> students) {
    List<String> firsts = new ArrayList<>();
    List<String> withInitials = new ArrayList<>();
    List<String> fulls = new ArrayList<>();
    for (RosterStudent student : students) {
      String first = titleCase(firstWord(student.getFirstName()));
      String last = titleCase(student.getLastName());
      firsts.add(first);
      withInitials.add(join(first, last.isEmpty() ? "" : last.substring(0, 1)));
      fulls.add(join(first, last));
    }

    Map<String, Integer> firstCounts = counts(firsts);
    Map<String, Integer> withInitialCounts = counts(withInitials);
    Map<String, Integer> fullCounts = counts(fulls);

    List<NameAndTeam> result = new ArrayList<>();
    for (int i = 0; i < students.size(); i++) {
      String name;
      if (firstCounts.get(firsts.get(i)) == 1) {
        name = firsts.get(i);
      } else if (withInitialCounts.get(withInitials.get(i)) == 1) {
        name = withInitials.get(i);
      } else if (fullCounts.get(fulls.get(i)) == 1) {
        name = fulls.get(i);
      } else {
        name = fulls.get(i) + "*";
      }
      List<String> teams = students.get(i).getTeams();
      String team = teams.isEmpty() ? "" : teams.get(0);
      result.add(new NameAndTeam(name, team));
    }
    return result;
  }

  /**
   * Splits the items into the given number of columns, filling column by column, with the column
   * lengths as balanced as possible: every column gets items.size() / columns items, and the first
   * items.size() % columns columns get one extra.
   *
   * @param <T> the type of item being laid out (e.g. a student, or a whole team)
   * @param items the items, in order
   * @param columns the number of columns, at least 1
   * @return a list of exactly {@code columns} lists, the first of which is never shorter than any
   *     other
   * @throws IllegalArgumentException if columns is less than 1
   */
  public <T> List<List<T>> layoutColumns(List<T> items, int columns) {
    if (columns < 1) {
      throw new IllegalArgumentException("columns must be at least 1");
    }
    int base = items.size() / columns;
    int extra = items.size() % columns;
    List<List<T>> result = new ArrayList<>();
    int start = 0;
    for (int c = 0; c < columns; c++) {
      int size = base + (c < extra ? 1 : 0);
      result.add(items.subList(start, start + size));
      start += size;
    }
    return result;
  }

  /**
   * Splits the items into columns of at most {@code perColumn} items, filling column by column:
   * every column except the last one is full. Unlike {@link #layoutColumns}, the number of columns
   * is not fixed; there are as many as needed, and always at least one (which is empty when there
   * are no items).
   *
   * @param <T> the type of item being laid out (e.g. a student, or a whole team)
   * @param items the items, in order
   * @param perColumn the most items in one column, at least 1
   * @return the columns, in order
   * @throws IllegalArgumentException if perColumn is less than 1
   */
  public <T> List<List<T>> chunkColumns(List<T> items, int perColumn) {
    if (perColumn < 1) {
      throw new IllegalArgumentException("perColumn must be at least 1");
    }
    List<List<T>> result = new ArrayList<>();
    for (int start = 0; start < items.size(); start += perColumn) {
      result.add(items.subList(start, Math.min(start + perColumn, items.size())));
    }
    if (result.isEmpty()) {
      result.add(List.of());
    }
    return result;
  }

  /**
   * Writes a CSV made of several side-by-side columns separated by a blank cell. The header line
   * repeats {@code headerCells} once per column; then there is one line per row of the longest
   * column. Each column is a list of rows, and each row a list of cells with the same length as
   * {@code headerCells}. Rows missing from shorter columns are written as blank cells.
   *
   * @param writer where to write the CSV
   * @param headerCells the cells of one column's header, e.g. ["Name", "Team"]
   * @param columns the columns, each a list of rows of cells
   * @throws IOException if writing fails
   */
  public void writeColumnsCsv(
      Writer writer, List<String> headerCells, List<List<List<String>>> columns)
      throws IOException {
    try (CSVPrinter csvPrinter = new CSVPrinter(writer, CSVFormat.DEFAULT)) {
      printColumns(csvPrinter, headerCells, columns);
    }
  }

  /**
   * Prints the side-by-side columns described in {@link #writeColumnsCsv} to a CSVPrinter, without
   * closing it, so that several tables can be printed to one CSV file.
   */
  private void printColumns(
      CSVPrinter csvPrinter, List<String> headerCells, List<List<List<String>>> columns)
      throws IOException {
    int width = headerCells.size();
    List<String> blanks = new ArrayList<>();
    for (int i = 0; i < width; i++) {
      blanks.add("");
    }
    int rows = columns.stream().mapToInt(List::size).max().orElse(0);

    List<String> header = new ArrayList<>();
    for (int c = 0; c < columns.size(); c++) {
      if (c > 0) {
        header.add("");
      }
      header.addAll(headerCells);
    }
    csvPrinter.printRecord(header);

    for (int r = 0; r < rows; r++) {
      List<String> row = new ArrayList<>();
      for (int c = 0; c < columns.size(); c++) {
        if (c > 0) {
          row.add("");
        }
        List<List<String>> column = columns.get(c);
        row.addAll(r < column.size() ? column.get(r) : blanks);
      }
      csvPrinter.printRecord(row);
    }
  }

  /**
   * Writes the "Name,Team" table: the entries balanced across the given number of column pairs,
   * filling column by column.
   *
   * @param writer where to write the CSV
   * @param entries the entries, in order
   * @param columns the number of "Name,Team" column pairs, at least 1
   * @throws IOException if writing fails
   * @throws IllegalArgumentException if columns is less than 1
   */
  public void writeName2TeamCsv(Writer writer, List<NameAndTeam> entries, int columns)
      throws IOException {
    List<List<List<String>>> layout = new ArrayList<>();
    for (List<NameAndTeam> column : layoutColumns(entries, columns)) {
      layout.add(nameTeamRows(column));
    }
    writeColumnsCsv(writer, List.of("Name", "Team"), layout);
  }

  /** The rows of one "Name,Team" column: one row per entry. */
  private static List<List<String>> nameTeamRows(List<NameAndTeam> entries) {
    return entries.stream().map(e -> List.of(e.name(), e.team())).toList();
  }

  /** The rows of one "Team,Name" column: one row per member of each of the teams, in order. */
  private static List<List<String>> teamNameRows(List<List<NameAndTeam>> teams) {
    List<List<String>> rows = new ArrayList<>();
    for (List<NameAndTeam> team : teams) {
      for (NameAndTeam entry : team) {
        rows.add(List.of(entry.team(), entry.name()));
      }
    }
    return rows;
  }

  /**
   * Groups the entries by team, one list per team, with the teams in case-insensitive alphabetical
   * order by name and the entries within each team in their original order. Entries with no team (a
   * blank team name) are collected into one extra group placed last, so that unassigned students
   * are still visible.
   *
   * @param entries the entries, in order
   * @return one list per team, teams sorted by name, unassigned students last
   */
  public List<List<NameAndTeam>> groupByTeam(List<NameAndTeam> entries) {
    Map<String, List<NameAndTeam>> byTeam =
        new TreeMap<>(String.CASE_INSENSITIVE_ORDER.thenComparing(Comparator.naturalOrder()));
    List<NameAndTeam> noTeam = new ArrayList<>();
    for (NameAndTeam entry : entries) {
      if (entry.team().isEmpty()) {
        noTeam.add(entry);
      } else {
        byTeam.computeIfAbsent(entry.team(), k -> new ArrayList<>()).add(entry);
      }
    }
    List<List<NameAndTeam>> result = new ArrayList<>(byTeam.values());
    if (!noTeam.isEmpty()) {
      result.add(noTeam);
    }
    return result;
  }

  /**
   * Writes the "Team,Name" table: the teams (see {@link #groupByTeam}) balanced across the given
   * number of column pairs, filling column by column, with one row per student. Columns are
   * balanced by number of teams, not number of students, so that a team is never split across two
   * columns.
   *
   * @param writer where to write the CSV
   * @param entries the entries, in order
   * @param columns the number of "Team,Name" column pairs, at least 1
   * @throws IOException if writing fails
   * @throws IllegalArgumentException if columns is less than 1
   */
  public void writeTeamTableCsv(Writer writer, List<NameAndTeam> entries, int columns)
      throws IOException {
    List<List<List<String>>> layout = new ArrayList<>();
    for (List<List<NameAndTeam>> column : layoutColumns(groupByTeam(entries), columns)) {
      layout.add(teamNameRows(column));
    }
    writeColumnsCsv(writer, List.of("Team", "Name"), layout);
  }

  /**
   * Writes the formatted teams CSV with {@link #NAMES_PER_COLUMN} names and {@link
   * #TEAMS_PER_COLUMN} teams per column; see {@link #writeFormattedTeamsCsv(Writer, List, int,
   * int)}.
   *
   * @param writer where to write the CSV
   * @param entries the entries, in order
   * @throws IOException if writing fails
   */
  public void writeFormattedTeamsCsv(Writer writer, List<NameAndTeam> entries) throws IOException {
    writeFormattedTeamsCsv(writer, entries, NAMES_PER_COLUMN, TEAMS_PER_COLUMN);
  }

  /**
   * Writes the formatted teams CSV: two tables, one after the other, each preceded by a title line.
   * The "by name" table lists every entry in "Name,Team" column pairs of {@code namesPerColumn}
   * rows each; the "by team" table lists the teams (see {@link #groupByTeam}) and their members in
   * "Team,Name" column pairs of {@code teamsPerColumn} teams each, so a team is never split. Both
   * fill column by column and use as many columns as needed. Imported into a spreadsheet, the file
   * only needs formatting and splitting into two tabs to become a team sheet.
   *
   * @param writer where to write the CSV
   * @param entries the entries, in order
   * @param namesPerColumn the most names in one column of the "by name" table, at least 1
   * @param teamsPerColumn the most teams in one column of the "by team" table, at least 1
   * @throws IOException if writing fails
   * @throws IllegalArgumentException if namesPerColumn or teamsPerColumn is less than 1
   */
  public void writeFormattedTeamsCsv(
      Writer writer, List<NameAndTeam> entries, int namesPerColumn, int teamsPerColumn)
      throws IOException {
    List<List<List<String>>> byName = new ArrayList<>();
    for (List<NameAndTeam> column : chunkColumns(entries, namesPerColumn)) {
      byName.add(nameTeamRows(column));
    }
    List<List<List<String>>> byTeam = new ArrayList<>();
    for (List<List<NameAndTeam>> column : chunkColumns(groupByTeam(entries), teamsPerColumn)) {
      byTeam.add(teamNameRows(column));
    }
    try (CSVPrinter csvPrinter = new CSVPrinter(writer, CSVFormat.DEFAULT)) {
      csvPrinter.printRecord("by name");
      printColumns(csvPrinter, List.of("Name", "Team"), byName);
      csvPrinter.printRecord("by team");
      printColumns(csvPrinter, List.of("Team", "Name"), byTeam);
    }
  }

  private static String join(String first, String lastPart) {
    if (first.isEmpty()) {
      return lastPart;
    }
    if (lastPart.isEmpty()) {
      return first;
    }
    return first + " " + lastPart;
  }

  private static Map<String, Integer> counts(List<String> values) {
    Map<String, Integer> result = new HashMap<>();
    for (String value : values) {
      result.merge(value, 1, Integer::sum);
    }
    return result;
  }
}