Jigsaw Sensemaking Report Generator

Fork of Jigsaw's report generator tooling, maintained by Cosla.

This package is maintained by Cosla as a fork of Jigsaw's original report generator in sensemaking-tools.

Fork and Attribution

@cosla/sensemaking-report-generator is a maintained fork of Jigsaw's report generation tooling from sensemaking-tools.

This package remains CLI compatible where practical, with fork-specific updates documented in this README.

This tool automatically generates interactive HTML reports from structured opinion data and AI-generated summaries. It takes CSV and JSON inputs and transforms them into a visual report featuring topic clusters, opinion distributions, and representative quotes.

Quick start (Report Generation)

If you are just here to generate a report from new data, follow these steps.

Prerequisites

• Node.js: Ensure you have Node.js installed on your machine.

Setup

Use this package in one of two ways:

• Install it in your project: npm install @cosla/sensemaking-report-generator
• Or run it directly with npx: npx @cosla/sensemaking-report-generator ...

Prepare your data

Provide the following files:

1. opinions.csv: The raw data containing participant quotes.
   • Required Columns: topic, opinion, quote (the quote), participant_id (participant ID).
   • Optional: AVERAGE_OF_2_BRIDGING (used for sorting quotes by importance).
2. summary.json: The AI-generated summary of the conversation.
   • Structure: Must contain a title, text (executive summary), and sub_contents (array of topic objects with title and text).
3. config.json: Basic configuration and customization options (e.g., logo path).
4. Logo: Optional image file (e.g., logo.png or logo.svg).

Configuration/customization

In config.json, optionally add these properties:

| Key | Type | Default | Description | | :--- | :--- | :--- | :--- | | logo | string | "" | Header image file. options: "logo.png" or "logo.svg". | | overview_chart | string | "toggle" | Overview chart display mode. Options: "toggle", "topics", or "opinions". | | number_of_top_opinions | number | 10 | The number of items to show in the opinions overview chart. | | number_of_sample_quotes | number | 4 | The number of quote previews to display for each opinion. | | chart_colors | array | ["#AFB42B", "#F4511E", "#3949AB", "#E52592", "#00897B", "#EFB22F", "#aaa"] | Array of color codes. |

Generate the report

Static (best for hosting):

npx sensemaking-report static \
  --opinions ./bridging_scores.csv \
  --summary ./report_data.json \
  --output ./report-output

Inline (single HTML file):

npx sensemaking-report inline \
  --opinions ./bridging_scores.csv \
  --summary ./report_data.json \
  --output ./report-output

Optional flags:

• --config ./config.json
• --logo ./logo.svg

Results

All results are written to the selected output folder:

• Static report: report-output/static/
• Inline report: report-output/inline/index.html

Configuration and input details

opinions.csv Format

The logic relies on specific headers. Ensure your CSV looks like this:

| topic | opinion | quote | participant_id |

summary.json Format

This file maps the visual topics to the text summaries.

{
  "title": "# Conversation Title",
  "text": "Executive summary paragraph...",
  "sub_contents": [
    {
      "title": "## Topic",
      "text": "Summary of the topic..."
    }
  ]
}

Development guide

If you are a developer looking to modify the report or build process, here is the architectural overview.

Project Structure

• input/: Raw data entry point.
• src/: Source code for the report.
  • script.js: Frontend logic and charts.
  • style.css: Visual styling.
  • index.mustache: HTML template used during the build.
• data.js: The ETL (Extract, Transform, Load) script. It converts the flat CSV into a hierarchical JSON structure (Topic -> Opinions -> Quotes).
• build.js: The orchestration script. It handles file cleaning, data processing, templating, and asset copying.

Key Commands

| Command | Description | | :--- | :--- | | npm run static | Builds the report separating HTML, CSS, JS, and JSON. Loads quotes lazily. | | npm run inline | Builds a single HTML file. Inlines all CSS, JS, and the full dataset. | | npm run preview | Builds static output and serves output/static with BrowserSync for local preview. | | npm run dev | Runs the dev server in dev.js (paired with predev to refresh temp data first). |

Data Pipeline (data.js)

1. Ingestion: Reads opinions.csv via csvtojson.
2. Grouping: Groups raw rows by topic, then by opinion.
3. Output: Generates data-static.json (lightweight payload) and data-inline.json (heavy payload with all quotes).

Visualization Logic (script.js)

• Frameworks: D3.v7 (charts), Tippy.js (tooltips), Mustache (templating).
• Charts:
  • Topic Chart: A stacked horizontal bar chart summarizing opinion distribution.
  • Opinion Chart: A flattened bar chart of the top opinions across all topics.
  • Donut Charts: Per-topic visualization of opinion breakdown.
• Data binding: Data is injected into window.PAYLOAD during the build process.

Customizing the build

The build.js file contains a task runner. You can add new build steps there.