ConceptsController.java

package edu.ucsb.cs.scaffold.controller;

import com.fasterxml.jackson.core.JsonProcessingException;

import com.fasterxml.jackson.core.type.TypeReference;

import com.fasterxml.jackson.databind.ObjectMapper;

import edu.ucsb.cs.scaffold.entity.Concept;

import edu.ucsb.cs.scaffold.entity.ConceptEdge;

import edu.ucsb.cs.scaffold.entity.Course;

import edu.ucsb.cs.scaffold.entity.PracticeProblem;

import edu.ucsb.cs.scaffold.errors.EntityNotFoundException;

import edu.ucsb.cs.scaffold.model.CreateConceptDTO;

import edu.ucsb.cs.scaffold.model.CreateSubconceptDTO;

import edu.ucsb.cs.scaffold.model.UpdateConceptDTO;

import edu.ucsb.cs.scaffold.model.UpdateSubconceptDTO;

import edu.ucsb.cs.scaffold.model.UserState;

import edu.ucsb.cs.scaffold.repository.ConceptEdgeRepository;

import edu.ucsb.cs.scaffold.repository.ConceptRepository;

import edu.ucsb.cs.scaffold.repository.CourseRepository;

import edu.ucsb.cs.scaffold.repository.PracticeProblemRepository;

import edu.ucsb.cs.scaffold.repository.UserStateRepository;

import edu.ucsb.cs.scaffold.services.ConceptGraphService;

import edu.ucsb.cs.scaffold.services.MarkdownService;

import io.swagger.v3.oas.annotations.Operation;

import io.swagger.v3.oas.annotations.Parameter;

import io.swagger.v3.oas.annotations.tags.Tag;

import java.util.ArrayList;

import java.util.Comparator;

import java.util.HashMap;

import java.util.HashSet;

import java.util.LinkedHashMap;

import java.util.List;

import java.util.Map;

import java.util.Objects;

import java.util.stream.Collectors;

import lombok.RequiredArgsConstructor;

import org.springframework.security.access.prepost.PreAuthorize;

import org.springframework.web.bind.annotation.DeleteMapping;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.PostMapping;

import org.springframework.web.bind.annotation.PutMapping;

import org.springframework.web.bind.annotation.RequestBody;

import org.springframework.web.bind.annotation.RequestParam;

import org.springframework.web.bind.annotation.RestController;

@Tag(name = "Concepts")

@RestController

public class ConceptsController extends ApiController {

  public static final int MAX_RENDERED_CONCEPT_LABEL_LENGTH = Concept.MAX_RENDERED_LABEL_LENGTH;

  public static final int MAX_RENDERED_SUBCONCEPT_LABEL_LENGTH =

      Concept.MAX_RENDERED_SUBCONCEPT_LABEL_LENGTH;

  // Applied to every new top-level concept; users cannot assign a color at creation time for

  // now. Top-level concepts are assumed throughout the frontend (node styling, drag-out

  // detail edges) to always have a real color; a null/blank color silently breaks that

  // styling (e.g. an SVG edge with no stroke color renders with stroke: none and is

  // invisible). Matches the "Level 1" swatch in the frontend's concept-graph legend.

  public static final String DEFAULT_TOP_LEVEL_COLOR = "#c99ffe";

  // The display order of subconcepts within a parent. sortOrder is author-controlled

  // (see reorderSubconcepts); the id tiebreaker makes the order deterministic even for

  // rows with equal or missing sortOrder (pre-backfill data, concurrent-create ties).

  private final ConceptRepository conceptRepository;

  private final PracticeProblemRepository practiceProblemRepository;

  private final ConceptEdgeRepository conceptEdgeRepository;

  private final CourseRepository courseRepository;

  private final UserStateRepository userStateRepository;

  private final MarkdownService markdownService;

  private final ConceptGraphService conceptGraphService;

  private final ObjectMapper objectMapper;

  @Operation(summary = "Get description/example/practiceUrl content for every concept in a course")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/content")

  public Map<Long, ConceptContentDTO> getContent(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

          new ConceptContentDTO(

              parentId,

  }

  @Operation(summary = "Get the top-level concepts for a course in table order")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/course")

  public List<CourseConceptDTO> getCourseConcepts(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

            concept ->

  }

  @Operation(summary = "Get the major concepts and their subconcepts for a course")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/graph")

  public List<MajorConceptDTO> getGraph(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

                    LinkedHashMap::new,

            major -> {

                          sub ->

                  new MajorConceptDTO(

                      subconceptDtos));

  }

  @Operation(summary = "Get the graph positions of the top-level concepts in a course")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/positions")

  public Map<Long, PositionDTO> getPositions(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

      }

  }

  @Operation(summary = "Get all top-level concepts for a course")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/top-level")

  public List<TopLevelConceptDTO> getTopLevelConcepts(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

            concept ->

  }

  @Operation(summary = "Get all subconcepts for a course in table-row format")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/subconcepts")

  public List<SubConceptTableRowDTO> getSubconcepts(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

            concept ->

  }

  @Operation(summary = "Get the prerequisite edges between concepts in a course")

  @PreAuthorize("hasRole('ROLE_USER')")

  @GetMapping("/api/concepts/edges")

  public List<EdgeDTO> getEdges(

      @Parameter(description = "id of the course") @RequestParam Long courseId) {

          new EdgeDTO(

  }

  @Operation(

      summary = "Create a new top-level concept",

      description =

          """

          Accepts a YAML (or JSON) request body. label, x, and y are required; color and

          level are not user-settable (every new top-level concept starts at level 1 with

          the default color, until a scaffold reset recomputes them). label, description,

          and example are Markdown; they are sanitized and canonicalized before being

          stored. YAML block scalars (|) make multi-line Markdown easy to enter through

          Swagger.

          """)

  @io.swagger.v3.oas.annotations.parameters.RequestBody(

      content =

          @io.swagger.v3.oas.annotations.media.Content(

              mediaType = "application/yaml",

              schema =

                  @io.swagger.v3.oas.annotations.media.Schema(

                      implementation = CreateConceptDTO.class),

              examples =

                  @io.swagger.v3.oas.annotations.media.ExampleObject(

                      value =

                          """

                          courseId: 1

                          label: Arrays

                          description: |

                            An *array* is a fixed-size collection of elements.

                          example: |

                            ```java

                            int[] arr = new int[5];

                            ```

                          x: 0

                          y: 0

                          """)))

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #dto.courseId)")

  @PostMapping(

      value = "/api/concept",

      consumes = {"application/yaml", "application/x-yaml", "application/json"})

  public Concept postConcept(@RequestBody CreateConceptDTO dto) throws EntityNotFoundException {

    }

        courseRepository

    }

    Concept concept =

  }

  @Operation(

      summary = "Create a new subconcept of a top-level concept",

      description =

          """

          Accepts a YAML (or JSON) request body. The parent must be an existing top-level

          concept in the same course, and the label must be unique among the parent's

          subconcepts. Subconcepts have no name, position, or color of their own. label,

          description, and example are Markdown; they are sanitized and canonicalized before

          being stored.

          """)

  @io.swagger.v3.oas.annotations.parameters.RequestBody(

      content =

          @io.swagger.v3.oas.annotations.media.Content(

              mediaType = "application/yaml",

              schema =

                  @io.swagger.v3.oas.annotations.media.Schema(

                      implementation = CreateSubconceptDTO.class),

              examples =

                  @io.swagger.v3.oas.annotations.media.ExampleObject(

                      value =

                          """

                          courseId: 1

                          parentConceptId: 42

                          label: Accessing a value

                          description: |

                            Use square brackets with an index.

                          example: |

                            ```java

                            int first = arr[0];

                            ```

                          """)))

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #dto.courseId)")

  @PostMapping(

      value = "/api/concept/subconcept",

      consumes = {"application/yaml", "application/x-yaml", "application/json"})

  public Concept postSubconcept(@RequestBody CreateSubconceptDTO dto)

      throws EntityNotFoundException {

    }

    }

        courseRepository

        conceptRepository

    }

          "parentConceptId %d is a subconcept; concepts can only be nested one level deep"

    }

    Concept concept =

  }

  @Operation(summary = "Update the label, description, and example of a top-level concept")

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #conceptId)")

  @PutMapping("/api/concept/put")

  public Concept putConcept(

      @Parameter(name = "conceptId") @RequestParam Long conceptId,

      @RequestBody UpdateConceptDTO dto)

      throws EntityNotFoundException {

        conceptRepository

          "concept %d is a subconcept; use PUT /api/concept/subconcept/put to update it"

    }

  }

  @Operation(summary = "Update the label, description, and example of a subconcept")

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #conceptId)")

  @PutMapping("/api/concept/subconcept/put")

  public Concept putSubconcept(

      @Parameter(name = "conceptId") @RequestParam Long conceptId,

      @RequestBody UpdateSubconceptDTO dto)

      throws EntityNotFoundException {

        conceptRepository

          "concept %d is not a subconcept; use PUT /api/concept/put to update it"

    }

  }

  @Operation(summary = "Add a practice problem URL to a concept")

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #conceptId)")

  @PostMapping("/api/concepts/practiceproblems/post")

  public PracticeProblem postPracticeProblem(

      @Parameter(name = "conceptId") @RequestParam Long conceptId,

      @Parameter(name = "url") @RequestParam String url)

      throws EntityNotFoundException {

        conceptRepository

    }

    }

    PracticeProblem practiceProblem =

  }

  @Operation(

      summary = "Designate an existing concept as a subconcept of a top-level concept",

      description =

          """

          Sets the parent of concept conceptId to parentConceptId. The concept must have no

          subconcepts of its own and no prerequisite edges (delete those first). The parent

          must be a top-level concept in the same course. The concept keeps its x,y position

          (if any) and takes on the parent's color.

          """)

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #conceptId)")

  @PutMapping("/api/concepts/designate")

  public Concept designateSubconcept(

      @Parameter(name = "conceptId") @RequestParam Long conceptId,

      @Parameter(name = "parentConceptId") @RequestParam Long parentConceptId)

      throws EntityNotFoundException {

        conceptRepository

        conceptRepository

    }

    }

          "parentConceptId %d is a subconcept; concepts can only be nested one level deep"

    }

          "concept %d has subconcepts of its own, so it cannot become a subconcept"

    }

          "concept %d has prerequisite edges; delete them before designating it as a subconcept"

    }

  }

  @Operation(

      summary = "Split a subconcept off into its own top-level concept",

      description =

          """

          Severs the concept's relationship with its parent, making it a top-level concept

          at the given x,y position. If the concept has no color, it inherits its former

          parent's color.

          """)

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #conceptId)")

  @PutMapping("/api/concepts/splitoff")

  public Concept splitOffSubconcept(

      @Parameter(name = "conceptId") @RequestParam Long conceptId,

      @Parameter(name = "x") @RequestParam Integer x,

      @Parameter(name = "y") @RequestParam Integer y)

      throws EntityNotFoundException {

        conceptRepository

    }

    }

  }

  @Operation(

      summary = "Reorder the subconcepts of a top-level concept",

      description =

          """

          Takes the complete ordered list of the parent's subconcept ids and rewrites every

          subconcept's sort position to its index in the list. Sending the whole permutation

          (rather than individual move operations) makes the update atomic and idempotent:

          concurrent reorders resolve to one complete, coherent ordering (last writer wins),

          and any sort-position ties left by concurrent subconcept creation are cleaned up as

          a side effect. The list must contain each current subconcept of the parent exactly

          once. Returns the subconcepts in their new order.

          """)

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #parentConceptId)")

  @PutMapping("/api/concepts/subconcepts/reorder")

  public List<SubconceptDTO> reorderSubconcepts(

      @Parameter(name = "parentConceptId") @RequestParam Long parentConceptId,

      @RequestBody List<Long> orderedSubconceptIds)

      throws EntityNotFoundException {

        conceptRepository

          "concept %d is a subconcept; only top-level concepts have subconcepts to reorder"

    }

          "orderedSubconceptIds must contain the id of each subconcept of concept %d exactly once"

    }

    }

            sub ->

  }

  @Operation(summary = "Create a prerequisite edge between two top-level concepts")

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #sourceConceptId)")

  @PostMapping("/api/concepts/edges/post")

  public ConceptEdge postConceptEdge(

      @Parameter(name = "sourceConceptId") @RequestParam Long sourceConceptId,

      @Parameter(name = "targetConceptId") @RequestParam Long targetConceptId)

      throws EntityNotFoundException {

        conceptRepository

        conceptRepository

    }

    }

    }

          "edge from concept %d to concept %d already exists"

    }

        sourceConceptId,

        targetConceptId)) {

          "edge from concept %d to concept %d would create a cycle"

    }

    ConceptEdge edge =

  }

  @Operation(summary = "Delete a prerequisite edge")

  @PreAuthorize("@CourseSecurity.hasConceptEdgeManagementPermissions(#root, #id)")

  @DeleteMapping("/api/concepts/edges/delete")

  public Object deleteConceptEdge(@Parameter(name = "id") @RequestParam Long id)

      throws EntityNotFoundException {

        conceptEdgeRepository

  }

  @Operation(

      summary = "Delete a concept; deleting a top-level concept also deletes its subconcepts")

  @PreAuthorize("@CourseSecurity.hasConceptManagementPermissions(#root, #conceptId)")

  @DeleteMapping("/api/concept/delete")

  public Object deleteConcept(@Parameter(name = "conceptId") @RequestParam Long conceptId)

      throws EntityNotFoundException {

        conceptRepository

    }

  }

  @Operation(

      summary = "Recompute a course's concept-graph structure",

      description =

          """

          Runs cycle detection, transitive reduction, longest-path leveling, and layout over

          a course's top-level concepts and prerequisite edges, persisting the results:

          edges found to be part of a cycle are colored red and excluded from the rest of

          the analysis (their endpoints keep whatever level/position they already had);

          edges made redundant by the graph's transitive structure are deleted; every other

          top-level concept is assigned a longest-path level (roots are level 1), a color

          from that level, and an x,y position (each level arranged left to right, sorted by

          prior x then id, centered at x=0, stacked above the previous level).

          """)

  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")

  @PostMapping("/api/course/scaffold/reset")

  public ScaffoldResetResponseDTO resetCourseScaffold(

      @Parameter(name = "courseId") @RequestParam Long courseId) throws EntityNotFoundException {

                edge ->

                edge ->

                concept ->