{"_id":"@cosla/sensemaking-report-generator","name":"@cosla/sensemaking-report-generator","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cosla/sensemaking-report-generator","version":"1.0.0","description":"Build static or inline Sensemaking HTML reports from opinions CSV and summary JSON inputs.","main":"build.js","bin":{"sensemaking-report":"cli.js"},"scripts":{"predev":"node build.js dev","dev":"node dev.js","preview":"node build.js preview","github":"node build.js github","static":"node build.js static","inline":"node build.js inline","build":"node build.js"},"repository":{"type":"git","url":"git+https://github.com/CoslaDigital/sensemaking-tools.git"},"keywords":["sensemaking","report","generator","csv","html"],"author":{"name":"Cosla"},"license":"ISC","type":"module","bugs":{"url":"https://github.com/CoslaDigital/sensemaking-tools/issues"},"homepage":"https://github.com/CoslaDigital/sensemaking-tools/tree/main/src/report_ui#readme","publishConfig":{"access":"public"},"dependencies":{"csvtojson":"^2.0.10","inline-source":"^8.0.3","mustache":"^4.2.0"},"devDependencies":{"browser-sync":"^3.0.4","express":"^5.2.1"},"gitHead":"9046bb46d91301895f6eb4b389c24cec14576a9b","_id":"@cosla/sensemaking-report-generator@1.0.0","_nodeVersion":"22.12.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-RvBcbTQZmqUn2hZmdA5txRutxo8Cl0gppC+jn9bU2THJVHENLnFhoEHqZW+8rV9nPTMzFvKMJ7m5sQLm+5lQ1g==","shasum":"6378fbee150baa59c16225040eed2a2ae20ec617","tarball":"https://registry.npmjs.org/@cosla/sensemaking-report-generator/-/sensemaking-report-generator-1.0.0.tgz","fileCount":33,"unpackedSize":549624,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDtsFSNkT4xpLut5YQZisN/6wjG83tBwXi5xRrFgd4cpwIhAPa0pAXb5CEwyra7JIMlNwo3eYjLpD+zpk4DZ/vpCHEH"}]},"_npmUser":{"name":"digitalwestie","email":"hello@rgianni.cc"},"directories":{},"maintainers":[{"name":"coslaconsul","email":"consul@cosla.gov.uk"},{"name":"digitalwestie","email":"hello@rgianni.cc"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sensemaking-report-generator_1.0.0_1779891003365_0.9723809951380338"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T14:10:03.245Z","1.0.0":"2026-05-27T14:10:03.497Z","modified":"2026-05-27T14:10:03.688Z"},"maintainers":[{"name":"coslaconsul","email":"consul@cosla.gov.uk"},{"name":"digitalwestie","email":"hello@rgianni.cc"}],"description":"Build static or inline Sensemaking HTML reports from opinions CSV and summary JSON inputs.","homepage":"https://github.com/CoslaDigital/sensemaking-tools/tree/main/src/report_ui#readme","keywords":["sensemaking","report","generator","csv","html"],"repository":{"type":"git","url":"git+https://github.com/CoslaDigital/sensemaking-tools.git"},"author":{"name":"Cosla"},"bugs":{"url":"https://github.com/CoslaDigital/sensemaking-tools/issues"},"license":"ISC","readme":"# Jigsaw Sensemaking Report Generator\n\nFork of Jigsaw's report generator tooling, maintained by Cosla.\n\nThis package is maintained by Cosla as a fork of Jigsaw's original report generator in [sensemaking-tools](https://github.com/Jigsaw-Code/sensemaking-tools).\n\n## Fork and Attribution\n\n`@cosla/sensemaking-report-generator` is a maintained fork of Jigsaw's report generation tooling from [sensemaking-tools](https://github.com/Jigsaw-Code/sensemaking-tools).\n\nThis package remains CLI compatible where practical, with fork-specific updates documented in this README.\n\nThis 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.\n\n## Quick start (Report Generation)\n\nIf you are just here to generate a report from new data, follow these steps.\n\n### Prerequisites\n*   **Node.js**: Ensure you have [Node.js](https://nodejs.org/) installed on your machine.\n\n### Setup\nUse this package in one of two ways:\n\n* Install it in your project: `npm install @cosla/sensemaking-report-generator`\n* Or run it directly with `npx`: `npx @cosla/sensemaking-report-generator ...`\n\n### Prepare your data\nProvide the following files:\n\n1.  **`opinions.csv`**: The raw data containing participant quotes.\n    *   *Required Columns:* `topic`, `opinion`, `quote` (the quote), `participant_id` (participant ID).\n    *   *Optional:* `AVERAGE_OF_2_BRIDGING` (used for sorting quotes by importance).\n2.  **`summary.json`**: The AI-generated summary of the conversation.\n    *   *Structure:* Must contain a `title`, `text` (executive summary), and `sub_contents` (array of topic objects with `title` and `text`).\n3.  **`config.json`**: [Basic configuration](#configuration-and-input-details) and customization options (e.g., logo path).\n4.  **Logo**: Optional image file (e.g., `logo.png` or `logo.svg`).\n\n#### Configuration/customization\nIn `config.json`, optionally add these properties:\n\n| Key | Type | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `logo` | `string` | `\"\"` | Header image file. options: `\"logo.png\"` or `\"logo.svg\"`. |\n| `overview_chart` | `string` | `\"toggle\"` | Overview chart display mode. Options: `\"toggle\"`, `\"topics\"`, or `\"opinions\"`. |\n| `number_of_top_opinions` | `number` | `10` | The number of items to show in the opinions overview chart. |\n| `number_of_sample_quotes` | `number` | `4` | The number of quote previews to display for each opinion. |\n| `chart_colors` | `array` | `[\"#AFB42B\", \"#F4511E\", \"#3949AB\", \"#E52592\", \"#00897B\", \"#EFB22F\", \"#aaa\"]` | Array of color codes. |\n\n### Generate the report\n\nStatic (best for hosting):\n\n```bash\nnpx sensemaking-report static \\\n  --opinions ./bridging_scores.csv \\\n  --summary ./report_data.json \\\n  --output ./report-output\n```\n\nInline (single HTML file):\n\n```bash\nnpx sensemaking-report inline \\\n  --opinions ./bridging_scores.csv \\\n  --summary ./report_data.json \\\n  --output ./report-output\n```\n\nOptional flags:\n- `--config ./config.json`\n- `--logo ./logo.svg`\n\n### Results\nAll results are written to the selected output folder:\n*   **Static report**: `report-output/static/`\n*   **Inline report**: `report-output/inline/index.html`\n\n---\n\n## Configuration and input details\n\n### `opinions.csv` Format\nThe logic relies on specific headers. Ensure your CSV looks like this:\n\n| topic | opinion | quote | participant_id |\n\n### `summary.json` Format\nThis file maps the visual topics to the text summaries.\n```json\n{\n  \"title\": \"# Conversation Title\",\n  \"text\": \"Executive summary paragraph...\",\n  \"sub_contents\": [\n    {\n      \"title\": \"## Topic\",\n      \"text\": \"Summary of the topic...\"\n    }\n  ]\n}\n```\n\n---\n\n## Development guide\n\nIf you are a developer looking to modify the report or build process, here is the architectural overview.\n\n### Project Structure\n\n- **`input/`**: Raw data entry point.\n- **`src/`**: Source code for the report.\n  - `script.js`: Frontend logic and charts.\n  - `style.css`: Visual styling.\n  - `index.mustache`: HTML template used during the build.\n- **`data.js`**: The ETL (Extract, Transform, Load) script. It converts the flat CSV into a hierarchical JSON structure (`Topic -> Opinions -> Quotes`).\n- **`build.js`**: The orchestration script. It handles file cleaning, data processing, templating, and asset copying.\n\n### Key Commands\n\n| Command | Description |\n| :--- | :--- |\n| `npm run static` | Builds the report separating HTML, CSS, JS, and JSON. Loads quotes lazily. |\n| `npm run inline` | Builds a single HTML file. Inlines all CSS, JS, and the full dataset. |\n| `npm run preview` | Builds static output and serves `output/static` with BrowserSync for local preview. |\n| `npm run dev` | Runs the dev server in `dev.js` (paired with `predev` to refresh temp data first). |\n\n### Data Pipeline (`data.js`)\n1. **Ingestion**: Reads `opinions.csv` via `csvtojson`.\n2. **Grouping**: Groups raw rows by `topic`, then by `opinion`.\n3. **Output**: Generates `data-static.json` (lightweight payload) and `data-inline.json` (heavy payload with all quotes).\n\n### Visualization Logic (`script.js`)\n- **Frameworks**: D3.v7 (charts), Tippy.js (tooltips), Mustache (templating).\n- **Charts**:\n  - *Topic Chart*: A stacked horizontal bar chart summarizing opinion distribution.\n  - *Opinion Chart*: A flattened bar chart of the top opinions across all topics.\n  - *Donut Charts*: Per-topic visualization of opinion breakdown.\n- **Data binding**: Data is injected into `window.PAYLOAD` during the build process.\n\n### Customizing the build\nThe `build.js` file contains a task runner. You can add new build steps there.","readmeFilename":"README.md","_rev":"1-67912d0ad85c5f37b7deb567e92701a3"}