Refactoring & Documentation with AI

@GetMapping("/api/pages/{id}/related")
public List<RelatedPage> getRelatedPages(@PathVariable Long id,
                                          @RequestParam(defaultValue = "5") int limit) {
    Page page = pageRepository.findById(id).orElseThrow();
    String text = page.getContent();
    String excerpt = text.length() > 200 ? text.substring(0, 200) + "..." : text;
    page.setExcerpt(excerpt);

    List<RelatedPage> related = embeddingIndex.nearest(id, limit);
    for (RelatedPage r : related) {
        String relatedText = r.getContent();
        r.setExcerpt(relatedText.length() > 200 ? relatedText.substring(0, 200) + "..." : relatedText);
    }
    return related;
}

$ claude "in @src/main/java/com/example/docsassistant/DocsController.java, extract the repeated
200-character excerpt logic in getRelatedPages into a private excerpt(String text) method and
use it in both places. Keep behavior identical and run the tests after."

#DocsController.java Extract the duplicated 200-character excerpt truncation in getRelatedPages
into a private excerpt(String text) helper method, and call it from both places it currently
appears inline. Don't change the truncation length or the "..." suffix.

 @GetMapping("/api/pages/{id}/related")
 public List<RelatedPage> getRelatedPages(@PathVariable Long id,
                                           @RequestParam(defaultValue = "5") int limit) {
     Page page = pageRepository.findById(id).orElseThrow();
-    String text = page.getContent();
-    String excerpt = text.length() > 200 ? text.substring(0, 200) + "..." : text;
-    page.setExcerpt(excerpt);
+    page.setExcerpt(excerpt(page.getContent()));

     List<RelatedPage> related = embeddingIndex.nearest(id, limit);
-    for (RelatedPage r : related) {
-        String relatedText = r.getContent();
-        r.setExcerpt(relatedText.length() > 200 ? relatedText.substring(0, 200) + "..." : relatedText);
-    }
+    related.forEach(r -> r.setExcerpt(excerpt(r.getContent())));
     return related;
 }
+
+private String excerpt(String text) {
+    return text.length() > 200 ? text.substring(0, 200) + "..." : text;
+}

public List<RelatedPage> recommendRelatedPages(Long pageId, int limit) {
    List<RelatedPage> results;
    if (pageId != null) {
        if (pageRepository.existsById(pageId)) {
            if (limit > 0) {
                results = embeddingIndex.nearest(pageId, limit);
            } else {
                results = List.of();
            }
        } else {
            results = List.of();
        }
    } else {
        results = List.of();
    }
    return results;
}

$ claude "decompose the nested if/else in recommendRelatedPages (same file) into a guard clause
plus a private isValidRequest(Long pageId, int limit) predicate. Every branch that currently
returns List.of() should be covered by the single guard. Run the tests after."

#DocsController.java Decompose the nested if/else in recommendRelatedPages into a single guard
clause that returns List.of(), plus a private isValidRequest(Long pageId, int limit) predicate.
Keep every branch that currently returns List.of() covered by that guard.

 public List<RelatedPage> recommendRelatedPages(Long pageId, int limit) {
-    List<RelatedPage> results;
-    if (pageId != null) {
-        if (pageRepository.existsById(pageId)) {
-            if (limit > 0) {
-                results = embeddingIndex.nearest(pageId, limit);
-            } else {
-                results = List.of();
-            }
-        } else {
-            results = List.of();
-        }
-    } else {
-        results = List.of();
-    }
-    return results;
+    if (!isValidRequest(pageId, limit)) {
+        return List.of();
+    }
+    return embeddingIndex.nearest(pageId, limit);
+}
+
+private boolean isValidRequest(Long pageId, int limit) {
+    return pageId != null && limit > 0 && pageRepository.existsById(pageId);
 }

#DocsController.java Rename the method calc(double[] queryVec, double[] pageVec) to
computeRelevanceScore, and update every call site in this file and its test class.

$ claude "rename calc(double[] queryVec, double[] pageVec) in
@src/main/java/com/example/docsassistant/DocsController.java to computeRelevanceScore, update every
call site under src/, including DocsControllerTest.java, and run the tests after."

-public double calc(double[] queryVec, double[] pageVec) {
+public double computeRelevanceScore(double[] queryVec, double[] pageVec) {
     return cosineSimilarity(queryVec, pageVec);
 }

import java.util.Comparator;
import java.util.stream.Collectors;

// ...

@Deprecated
private List<RelatedPage> legacyLinearScan(Long pageId, int limit) {
    return pageRepository.findAll().stream()
            .filter(p -> !p.getId().equals(pageId))
            .sorted(Comparator.comparingDouble(p -> -computeRelevanceScore(embed(pageId), embed(p.getId()))))
            .limit(limit)
            .collect(Collectors.toList());
}

$ claude "search @src/main/java/com/example/docsassistant/ for calls to legacyLinearScan. If nothing
else calls it, delete the method and any imports that become unused."

-import java.util.Comparator;
-import java.util.stream.Collectors;
-
 // ...

-@Deprecated
-private List<RelatedPage> legacyLinearScan(Long pageId, int limit) {
-    return pageRepository.findAll().stream()
-            .filter(p -> !p.getId().equals(pageId))
-            .sorted(Comparator.comparingDouble(p -> -computeRelevanceScore(embed(pageId), embed(p.getId()))))
-            .limit(limit)
-            .collect(Collectors.toList());
-}

#DocsController.java Add a Javadoc comment to getRelatedPages explaining the id and limit
parameters, what it returns, and that it throws when no page matches the id. Match the Javadoc
style already used on listPages in this file.

$ claude "add Javadoc to getRelatedPages in @src/main/java/com/example/docsassistant/DocsController.java,
matching the style of the existing listPages Javadoc in the same file"

+/**
+ * Returns pages related to the page with the given id, ranked by embedding similarity.
+ *
+ * @param id    the id of the page to find related pages for
+ * @param limit the maximum number of related pages to return
+ * @return the related pages, most similar first
+ * @throws java.util.NoSuchElementException if no page has the given id
+ */
 @GetMapping("/api/pages/{id}/related")
 public List<RelatedPage> getRelatedPages(@PathVariable Long id,
                                           @RequestParam(defaultValue = "5") int limit) {

/create-readme

$ claude "write a README.md for this repository: what DocsAssistant API does, how to run
src/main/java/com/example/docsassistant with Maven, how to run ingest/build_index.py to rebuild
the embedding index, and how to run the tests. Don't include a license section or a full API
reference -- link to those separately if they exist."

$ claude "write an ADR using the MADR template (Context and Problem Statement, Considered Options,
Decision Outcome, Consequences) documenting why DocsAssistant API's embedding index uses FAISS (in
ingest/build_index.py) rather than a pgvector-backed table, given that the index is rebuilt offline
and served read-only. List both FAISS and pgvector under Considered Options. Save it as
docs/adr/0007-embedding-index-choice.md."

# Use a FAISS index file for related-page lookup

## Context and Problem Statement
DocsAssistant API's related-pages feature needs nearest-neighbor lookup over page embeddings.
The index is rebuilt offline by ingest/build_index.py and served read-only by DocsController;
no write path exists at query time. Where should the embedding index live?

## Considered Options
* FAISS index file built by ingest/build_index.py and loaded at startup
* pgvector-backed table queried per request

## Decision Outcome
Chosen option: "FAISS index file built by ingest/build_index.py and loaded at startup", because
the index is rebuilt offline and only ever read at query time, so a database write path adds
nothing.

### Consequences
* Good, because query latency does not depend on the database under load.
* Bad, because the index must be rebuilt and redeployed after every content change, instead of
  updating in place.
* Bad, because filtering related pages by metadata (e.g. by section) needs a post-filter step,
  since FAISS itself is not metadata-aware.

$ claude "find deprecated Spring MVC annotations in @src/main/java/com/example/docsassistant/,
suggest their current replacements, and apply them one file at a time, running the tests after
each file"

def cosine_similarity(query_vec, page_vec):
    dot = sum(q * p for q, p in zip(query_vec, page_vec))
    norm_q = sum(q * q for q in query_vec) ** 0.5
    norm_p = sum(p * p for p in page_vec) ** 0.5
    if norm_q == 0 or norm_p == 0:
        return 0.0
    return dot / (norm_q * norm_p)

$ claude "translate the cosine_similarity function in @ingest/build_index.py into a Java static
method double[] -> double[] -> double in a new class
src/main/java/com/example/docsassistant/ScoreUtils.java, matching the zero-norm guard and zip()'s
stop-at-the-shorter-vector behavior, and add a
unit test under src/test/java/com/example/docsassistant/ that checks the same cases the Python
version would return 0.0 for."

package com.example.docsassistant;

public final class ScoreUtils {

    private ScoreUtils() {
    }

    public static double cosineSimilarity(double[] queryVec, double[] pageVec) {
        // zip() in the Python version stops at the shorter vector; the norms still use every element.
        int n = Math.min(queryVec.length, pageVec.length);
        double dot = 0.0;
        for (int i = 0; i < n; i++) {
            dot += queryVec[i] * pageVec[i];
        }
        double normQ = 0.0;
        for (double q : queryVec) {
            normQ += q * q;
        }
        double normP = 0.0;
        for (double p : pageVec) {
            normP += p * p;
        }
        if (normQ == 0.0 || normP == 0.0) {
            return 0.0;
        }
        return dot / (Math.sqrt(normQ) * Math.sqrt(normP));
    }
}