update-solution-analyzer

# Update Solution Analyzer Scripts ## Before Modifying a Script Always review the relevant script documentation in `Tools/Solutions Analyzer/script-docs/` first. For changes to a CSV output file's columns or semantics, also review the corresponding per-CSV reference page in `Tools/Solutions Analyzer/script-docs/csv/` (one file per CSV). ## Script Documentation Updates When updating a script, update the corresponding doc in `script-docs/` to reflect: - Script parameters added or changed - Output file changes — for new/renamed/removed CSV columns, **edit the per-CSV page in `script-docs/csv/<csv-name>.md`** (the script doc only lists CSVs as a summary table with links; it does not duplicate column tables) - Changes to analysis methods or logic - New CSV output: create a new page under `script-docs/csv/`, add a row to the summary table in the script doc, and add the new CSV to `script-docs/csv/README.md` (both the "By generating script" and "By role" sections) ## README Changelog **Required for feature additions and behavior changes; optional for small bug fixes.** New features, changed analysis logic, new/renamed/removed CSV columns, parameter changes, and other user-visible behavior changes must appear in the changelog. Pure bug fixes — such as correcting a typo, fixing a crash, escape-character tweaks, regex corrections, or one-line fixes that restore intended behavior without changing it — may be logged at your discretion but are not required. When a changelog entry is warranted, update the `## Version History` section in `Tools/Solutions Analyzer/README.md`: - Add the change under the **latest version heading** at the top of the changelog - If the latest version has not been committed yet (i.e., it already has uncommitted changes in the changelog), add to that existing version — do **not** create a new version entry - If the latest version was already committed, create a new version entry with an incremented version number and a short descriptive title - Each entry should be a bullet under a bold category heading (e.g., `**Fix Name:**`) - Be concise but specific: state what changed, why, and what the user-visible impact is ## CSV Output Changes When adding or removing a CSV output file from the mapper: - Update `upload_to_kusto.py` → `SOLUTION_ANALYZER_FILES` list to add/remove the file ## Static and Interactive Index Synchronization The documentation generator produces **two parallel sets of index pages** that must stay in sync: 1. **Static indexes** (`generate_connector_docs.py`): Markdown index pages — `solutions-index.md`, `connectors-index.md`, `tables-index.md`, `content/content-index.md`, etc. 2. **Interactive index** (`generate_interactive_docs.py`): HTML page with DataTables.js — `index.html` with tabs for Solutions, Connectors, Tables, and Content. **When modifying any index generation logic**, apply the same change to BOTH: - Data filtering/inclusion rules (which connectors or tables to show) - Status classification logic (Active/Deprecated/Unpublished/Discovered) - Icon usage and legend entries - Special-case handling (placeholder names like `<PlaybookName>`, "GitHub Only" solution name) - Link generation (collection method links, content item links, parser routing) - Column additions or removals - Description cleanup (quote stripping, truncation) ## Markdown and HTML Entity Page Synchronization The doc generator produces **both static markdown and HTML versions** of every entity page. - **Markdown pages** (`generate_connector_docs.py`): Primary data source — all content, counts, tables, and formatting are defined here. - **HTML entity pages** (`generate_interactive_docs.py` → `_generate_html_pages()`): Auto-generated from markdown via Python `markdown` library. In most cases, changing `generate_connector_docs.py` is sufficient because HTML pages derive from markdown. But if the change involves: - Navigation or link targets - HTML-specific rendering (e.g., DataTables on schema tables) - Heading structure changes ...also update `generate_interactive_docs.py`.