docs: Enhance JSDoc for build scripts (#8510)

Author: tobiu

buildScripts/createReleaseIndex.mjs

@@ -7,6 +7,24 @@ import matter          from 'gray-matter';
 import semver          from 'semver';
 import {sanitizeInput} from './util/Sanitizer.mjs';
 
+/**
+ * @module buildScripts.createReleaseIndex
+ * @summary Generates a hierarchical JSON index of Release Notes for the Neo.mjs Portal application.
+ *
+ * This script scans local markdown files in `resources/content/release-notes` and constructs a
+ * structured JSON index (`releases.json`). This index is consumed by the Portal's "Release Notes"
+ * section, allowing users to browse history grouped by Major Version.
+ *
+ * **Key Features:**
+ * - **Metadata Extraction:** Parses frontmatter (`tagName`, `publishedAt`) but falls back to file stats/names if needed.
+ * - **SemVer Grouping:** Automatically groups releases by Major Version (e.g., "v5", "v6") using `semver`.
+ * - **Tree-Ready Output:** Generates a flat-tree structure with `parentId` references, optimized for `Neo.tree.List`.
+ *
+ * @see apps/portal/view/release/MainContainer.mjs
+ * @see buildScripts/createTicketIndex.mjs
+ * @keywords portal, releases, changelog, semver, build-script, knowledge-base
+ */
+
 const ROOT_DIR    = process.cwd();
 const RELEASE_DIR = path.resolve(ROOT_DIR, 'resources/content/release-notes');
 const OUTPUT_FILE = path.resolve(ROOT_DIR, 'apps/portal/resources/data/releases.json');
@@ -21,11 +39,18 @@ const OUTPUT_FILE = path.resolve(ROOT_DIR, 'apps/portal/resources/data/releases.
  */
 
 /**
- * Scans the release notes directory and generates a JSON index.
- * @param {Object} options
- * @param {String} options.inputDir - Directory containing markdown release notes
- * @param {String} options.outputFile - Path to the output JSON file
- * @returns {Promise<void>}
+ * Core logic to scan and index release note markdown files.
+ *
+ * 1.  Glob-scans `resources/content/release-notes/*.md`.
+ * 2.  Extracts version numbers and dates (handling both frontmatter and filesystem fallbacks).
+ * 3.  Groups releases into Major Version buckets (e.g., "v1", "v2").
+ * 4.  Sorts majors and minors descending.
+ * 5.  Flattens the structure for `Neo.data.Store` consumption.
+ *
+ * @param {Object} options Configuration options
+ * @param {String} [options.inputDir] - Directory containing markdown release notes (defaults to `resources/content/release-notes`)
+ * @param {String} [options.outputFile] - Path to the output JSON file (defaults to `apps/portal/resources/data/releases.json`)
+ * @returns {Promise<void>} Resolves when the JSON file is written
  */
 async function createReleaseIndex(options = {}) {
     const inputDir   = options.inputDir || RELEASE_DIR;
@@ -157,6 +182,14 @@ async function createReleaseIndex(options = {}) {
     console.log(`Release index written to ${outputFile}`);
 }
 
+/**
+ * CLI entry point for the script.
+ * Handles argument parsing using `commander` and invokes the main `createReleaseIndex` function.
+ *
+ * Supported flags:
+ * - `-i, --input <path>`: Custom input directory
+ * - `-o, --output <path>`: Custom output file path
+ */
 async function runCli() {
     const program = new Command();
 

buildScripts/createTicketIndex.mjs

@@ -7,6 +7,25 @@ import matter          from 'gray-matter';
 import semver          from 'semver';
 import {sanitizeInput} from './util/Sanitizer.mjs';
 
+/**
+ * @module buildScripts.createTicketIndex
+ * @summary Generates a hierarchical JSON index of GitHub tickets for the Neo.mjs Portal application.
+ *
+ * This script is a critical part of the **Portal Knowledge Hub** data pipeline. It parses local markdown
+ * files (synced from GitHub Issues) and transforms them into a lightweight, structured JSON index (`tickets.json`).
+ * This index drives the `TreeList` navigation in the Portal's "Tickets" section.
+ *
+ * **Key Features:**
+ * - **Dual-Source Scanning:** Reads from both active issues (`resources/content/issues`) and the issue archive (`resources/content/issue-archive`).
+ * - **Intelligent Filtering:** Includes high-value tickets (bug, feature, epic) while excluding noise (chore, task) to ensure high signal-to-noise ratio for SEO and AI.
+ * - **Hierarchical Grouping:** Groups tickets by "Latest" (active) or by Release Version (archived), sorted semantically.
+ * - **TreeList Optimization:** Outputs a flat-tree structure compatible with `Neo.tree.List` and `Neo.data.Store`.
+ *
+ * @see apps/portal/view/news/tickets/MainContainer.mjs
+ * @see buildScripts/createReleaseIndex.mjs
+ * @keywords portal, tickets, seo, json-index, build-script, knowledge-base
+ */
+
 const ROOT_DIR    = process.cwd();
 const ISSUES_DIR  = path.resolve(ROOT_DIR, 'resources/content/issues');
 const ARCHIVE_DIR = path.resolve(ROOT_DIR, 'resources/content/issue-archive');
@@ -18,12 +37,21 @@ const INCLUDE_LABELS = new Set(['bug', 'feature', 'enhancement', 'documentation'
 const EXCLUDE_LABELS = new Set(['chore', 'task', 'agent-task']);
 
 /**
- * Scans the issues and issue-archive directories and generates a hierarchical JSON index.
- * @param {Object} options
- * @param {String} options.issuesDir - Directory containing active markdown tickets
- * @param {String} options.archiveDir - Directory containing archived markdown tickets (versioned folders)
- * @param {String} options.outputFile - Path to the output JSON file
- * @returns {Promise<void>}
+ * Core logic to scan, filter, and index ticket markdown files.
+ *
+ * This function performs the heavy lifting:
+ * 1.  Glob-scans the configured directories for `.md` files.
+ * 2.  Parses YAML frontmatter to extract metadata (id, title, labels, dates).
+ * 3.  Applies inclusion/exclusion label logic.
+ * 4.  Groups tickets by version (directory name) or 'Latest'.
+ * 5.  Sorts groups by SemVer and tickets by date/ID.
+ * 6.  Flattens the result into a `Neo.data.Store` compatible array.
+ *
+ * @param {Object} options Configuration options
+ * @param {String} [options.issuesDir] - Directory containing active markdown tickets (defaults to `resources/content/issues`)
+ * @param {String} [options.archiveDir] - Directory containing archived markdown tickets (defaults to `resources/content/issue-archive`)
+ * @param {String} [options.outputFile] - Path to the output JSON file (defaults to `apps/portal/resources/data/tickets.json`)
+ * @returns {Promise<void>} Resolves when the JSON file is written
  */
 async function createTicketIndex(options = {}) {
     const issuesDir  = options.issuesDir  || ISSUES_DIR;
@@ -178,6 +206,15 @@ async function createTicketIndex(options = {}) {
     console.log(`Ticket index written to ${outputFile}`);
 }
 
+/**
+ * CLI entry point for the script.
+ * Handles argument parsing using `commander` and invokes the main `createTicketIndex` function.
+ *
+ * Supported flags:
+ * - `-i, --issues <path>`: Custom issues directory
+ * - `-a, --archive <path>`: Custom archive directory
+ * - `-o, --output <path>`: Custom output file path
+ */
 async function runCli() {
     const program = new Command();