From c578cc95d153c3106a63f61211a90ba08c35b348 Mon Sep 17 00:00:00 2001
From: Lucas Azevedo <lhs_azevedo@hotmail.com>
Date: Sun, 3 Nov 2024 11:02:44 -0300
Subject: [PATCH] Fix search index for entries without parent book (#160)

* Fix search index for entries without parent books

This commit enhances the search index generation process by providing
more meaningful descriptions for entries that lack a parent <book>
element. Additionally, refactors writeJsonIndex() into smaller methods.

Fixes #159

* Prefer array_key_exists over isset

* Return set elements immediately

* Rename processIndexForSearch to improve clarity

Also, updated the doc block with additional context.
---
 phpdotnet/phd/Package/PHP/Web.php | 68 +++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 18 deletions(-)

diff --git a/phpdotnet/phd/Package/PHP/Web.php b/phpdotnet/phd/Package/PHP/Web.php
index 291c54f6..83792249 100644
--- a/phpdotnet/phd/Package/PHP/Web.php
+++ b/phpdotnet/phd/Package/PHP/Web.php
@@ -234,8 +234,25 @@ public function footer($id) {
 
     protected function writeJsonIndex() {
         v("Writing search indexes..", VERBOSE_FORMAT_RENDERING);
-        $ids = array();
-        $desc = array();
+        [$entries, $descriptions] = $this->processJsonIndex();
+        file_put_contents(
+            $this->getOutputDir() . "search-index.json",
+            json_encode($entries)
+        );
+        file_put_contents(
+            $this->getOutputDir() . "search-description.json",
+            json_encode($descriptions)
+        );
+        v("Index written", VERBOSE_FORMAT_RENDERING);
+    }
+
+    /**
+     * Processes the index to extract entries and descriptions. These are
+     * used to generate the search index and the descriptions JSON files.
+     */
+    private function processJsonIndex(): array {
+        $entries = [];
+        $descriptions = [];
         foreach($this->indexes as $id => $index) {
             if (!$index["chunk"]) {
                 continue;
@@ -243,26 +260,41 @@ protected function writeJsonIndex() {
 
             if ($index["sdesc"] === "" && $index["ldesc"] !== "") {
                 $index["sdesc"] = $index["ldesc"];
-
-                $parentId = $index['parent_id'];
-                // isset() to guard against undefined array keys, either for root
-                // elements (no parent) or in case the index structure is broken.
-                while (isset($this->indexes[$parentId])) {
-                    $parent = $this->indexes[$parentId];
-                    if ($parent['element'] === 'book') {
-                        $index["ldesc"] = Format::getLongDescription($parent['docbook_id']);
-                        break;
-                    }
-                    $parentId = $parent['parent_id'];
+                $bookOrSet = $this->findParentBookOrSet($index['parent_id']);
+                if ($bookOrSet) {
+                    $index["ldesc"] = Format::getLongDescription(
+                        $bookOrSet['docbook_id']
+                    );
                 }
             }
 
-            $ids[] = array($index["sdesc"], $index["filename"], $index["element"]);
-            $desc[$id] = $index["ldesc"];
+            $entries[] = [
+                $index["sdesc"], $index["filename"], $index["element"]
+            ];
+            $descriptions[$id] = $index["ldesc"];
         }
-        file_put_contents($this->getOutputDir() . "search-index.json", json_encode($ids));
-        file_put_contents($this->getOutputDir() . "search-description.json", json_encode($desc));
-        v("Index written", VERBOSE_FORMAT_RENDERING);
+        return [$entries, $descriptions];
+    }
+
+    /**
+     * Finds the closest parent book or set in the index hierarchy.
+     */
+    private function findParentBookOrSet(string $id): ?array
+    {
+        // array_key_exists() to guard against undefined array keys, either for
+        // root elements (no parent) or in case the index structure is broken.
+        while (array_key_exists($id, $this->indexes)) {
+            $parent = $this->indexes[$id];
+            $element = $parent['element'];
+
+            if ($element === 'book' || $element === 'set') {
+                return $parent;
+            }
+
+            $id = $parent['parent_id'];
+        }
+
+        return null;
     }
 
     public function loadSourcesInfo() {