@cosla/sensemaking-report-builder 0.1.0 → 0.1.2

package/README.md

@@ -55,7 +55,9 @@ Defaults: opinions `<inputDir>/opinions.csv`, summary `<inputDir>/summary.json`,
 
 | Arg / flag | Purpose | Default |
 |------------|---------|---------|
-| `inline` \| `static` | Build mode (**required**) | — |
+| `inline` \| `static` | Build mode (**required** for builds) | — |
+| `config-schema` | Print config JSON Schema to stdout (no inputs) | — |
+| `--schema-version` | With `config-schema`: schema version to print | latest (`1`) |
 | `--inputDir` | Base dir for default input paths | `./input` |
 | `--opinions` / `--bridging_scores` | Opinions / bridging scores CSV | `<inputDir>/opinions.csv` |
 | `--summary` | Summary JSON (`report_data.json`) | `<inputDir>/summary.json` |
@@ -64,6 +66,19 @@ Defaults: opinions `<inputDir>/opinions.csv`, summary `<inputDir>/summary.json`,
 | `--output` | **inline only:** path to HTML file | `./output/report.html` |
 | `--outputDir` | **static only:** output directory | `./output` |
 
+### Config schema
+
+```bash
+npx @cosla/sensemaking-report-builder config-schema
+npx @cosla/sensemaking-report-builder config-schema --schema-version 1
+```
+
+Prints a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12/schema) document for supported `config.json` keys (`schemas/config.v1.json`), including application field `config_schema_version`. Unknown `--schema-version` values fail with a clear error.
+
+```bash
+npm run smoke   # validates config-schema output
+```
+
 Logo and translations are configured in `config.json` (not CLI flags). Place `logo.svg` / `logo.png` next to that config (under `--inputDir` when using dir mode).
 
 ## Input contracts
@@ -90,7 +105,7 @@ Same shape as Python `sensemaking-report-text` / `report_data.json`: `text`, `su
 | `low_sample_warning_threshold` | Low-sample warning threshold |
 | `topic_colors` / `chart_colors` | Overview chart colours |
 | `demographic_colors` | Participant chart colours |
-| `excludedTopics` / `excludedOpinions` | Hide named topics/opinions |
+| `excluded_topics` / `excluded_opinions` | Hide named topics/opinions (exact match to CSV columns) |
 
 ### Predicted agreement (optional)
 

package/bin/cli.js

@@ -3,6 +3,7 @@ import { runBuild } from "../build.js";
 
 runBuild(process.argv, process.cwd())
   .then((result) => {
+    if (result.command === "config-schema") return;
     const out = result.output || result.outputDir;
     console.log(`Standalone report generated: ${out}`);
   })

package/build.js

@@ -10,7 +10,11 @@ import { execSync } from "node:child_process";
 import csv from "csvtojson";
 import mustache from "mustache";
 import { inlineSource } from "inline-source";
-import { processReportData, resolveBuildOptions } from "./data.js";
+import {
+  loadConfigSchema,
+  processReportData,
+  resolveBuildOptions,
+} from "./data.js";
 
 const WORK_DIR_NAME = ".py-report-ui-work";
 
@@ -173,6 +177,13 @@ function inlineFontDataUris(html, fontsDir) {
 export async function runBuild(argv = process.argv, cwd = process.cwd()) {
   const options = resolveBuildOptions(argv, cwd);
   const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+
+  if (options.command === "config-schema") {
+    const schema = loadConfigSchema(options.schemaVersion, packageRoot);
+    process.stdout.write(`${JSON.stringify(schema, null, 2)}\n`);
+    return { command: "config-schema" };
+  }
+
   const artefactRoot =
     options.command === "inline"
       ? path.dirname(options.output)
@@ -296,6 +307,7 @@ if (isMain) {
   } else {
     runBuild(process.argv, process.cwd())
       .then((result) => {
+        if (result.command === "config-schema") return;
         console.log(
           `Standalone report generated: ${result.output || result.outputDir}`,
         );

package/data.js

@@ -24,18 +24,50 @@ const demographics_prefix = "demo:";
 
 /**
  * @typedef {Object} BuildOptions
- * @property {"inline"|"static"} command
- * @property {string} inputDir
- * @property {string|null} output
- * @property {string|null} outputDir
- * @property {string} opinionsPath
- * @property {string} summaryPath
- * @property {string|null} predictedPath
- * @property {string|null} configPath
- * @property {boolean} predictedExplicit
- * @property {boolean} configExplicit
+ * @property {"inline"|"static"|"config-schema"} command
+ * @property {string|null} [schemaVersion]
+ * @property {string} [inputDir]
+ * @property {string|null} [output]
+ * @property {string|null} [outputDir]
+ * @property {string} [opinionsPath]
+ * @property {string} [summaryPath]
+ * @property {string|null} [predictedPath]
+ * @property {string|null} [configPath]
+ * @property {boolean} [predictedExplicit]
+ * @property {boolean} [configExplicit]
  */
 
+/** Latest shipped config schema version (omit `--schema-version` → this). */
+export const LATEST_CONFIG_SCHEMA_VERSION = 1;
+
+const CONFIG_SCHEMA_FILES = {
+  1: "config.v1.json",
+};
+
+/**
+ * Loads a config JSON Schema document for the given version.
+ * @param {string|number|null|undefined} schemaVersion
+ * @param {string} packageRoot Absolute path to the package root (directory of build.js).
+ * @returns {object}
+ */
+export function loadConfigSchema(schemaVersion, packageRoot) {
+  const version =
+    schemaVersion === undefined || schemaVersion === null || schemaVersion === ""
+      ? LATEST_CONFIG_SCHEMA_VERSION
+      : Number(schemaVersion);
+  if (!Number.isInteger(version) || !CONFIG_SCHEMA_FILES[version]) {
+    const supported = Object.keys(CONFIG_SCHEMA_FILES).join(", ");
+    throw new Error(
+      `Unknown config schema version "${schemaVersion}". Supported: ${supported}.`,
+    );
+  }
+  const schemaPath = path.join(packageRoot, "schemas", CONFIG_SCHEMA_FILES[version]);
+  if (!fs.existsSync(schemaPath)) {
+    throw new Error(`Config schema file not found: ${schemaPath}`);
+  }
+  return JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+}
+
 /**
  * Parses argv flags into a Map of key -> value.
  * @param {string[]} args
@@ -69,16 +101,26 @@ export function resolveBuildOptions(argv = process.argv, cwd = process.cwd()) {
   const commandToken = args[0] && !args[0].startsWith("--") ? args[0] : null;
   if (!commandToken) {
     throw new Error(
-      'Build mode is required. Use "inline" or "static" as the first argument.',
+      'Command is required. Use "inline", "static", or "config-schema" as the first argument.',
     );
   }
+
+  const flags = parseFlags(args);
+
+  if (commandToken === "config-schema") {
+    return {
+      command: commandToken,
+      schemaVersion: flags.has("schema-version")
+        ? flags.get("schema-version")
+        : null,
+    };
+  }
+
   if (commandToken !== "inline" && commandToken !== "static") {
     throw new Error(
-      `Unsupported command "${commandToken}". Use "inline" or "static".`,
+      `Unsupported command "${commandToken}". Use "inline", "static", or "config-schema".`,
     );
   }
-
-  const flags = parseFlags(args);
   const hasOutput = flags.has("output");
   const hasOutputDir = flags.has("outputDir");
 
@@ -380,6 +422,8 @@ export function processReportData({
   }
 
   const overviewChart = config.overview_chart || "toggle";
+  const excludedTopics = new Set(config.excluded_topics || []);
+  const excludedOpinions = new Set(config.excluded_opinions || []);
   const reportOptions = {
     logo: config.logo || "",
     overviewChart,
@@ -441,34 +485,43 @@ export function processReportData({
    * @returns {Object[]}
    */
   function groupOpinions(opinionsList) {
-    const byTopic = groupBy(opinionsList, "topic");
-    return byTopic.map(([topicText, topicOpinions]) => {
-      const topicMatch = (summary.sub_contents || []).find(
-        (t) => stripMarkdownHeader(t.title) === topicText,
-      );
-      const topicId = generateId(topicText, true);
-      const byOpinion = groupBy(topicOpinions, "opinion").map(([_, values]) => ({
-        opinionID: generateId(values[0].opinion),
-        fullID: `${topicId}-${generateId(values[0].opinion)}`,
-        text: values[0].opinion,
-        count: values.length,
-        quotes: sortAndExtractQuotes(values),
-      }));
-
-      byOpinion.sort((a, b) => {
-        if (a.text === "Other") return 1;
-        if (b.text === "Other") return -1;
-        return b.count - a.count;
-      });
+    const byTopic = groupBy(opinionsList, "topic").filter(
+      ([topicText]) => !excludedTopics.has(topicText),
+    );
+    return byTopic
+      .map(([topicText, topicOpinions]) => {
+        const topicMatch = (summary.sub_contents || []).find(
+          (t) => stripMarkdownHeader(t.title) === topicText,
+        );
+        const topicId = generateId(topicText, true);
+        const keptOpinions = topicOpinions.filter(
+          (row) => !excludedOpinions.has(row.opinion),
+        );
+        const byOpinion = groupBy(keptOpinions, "opinion").map(
+          ([_, values]) => ({
+            opinionID: generateId(values[0].opinion),
+            fullID: `${topicId}-${generateId(values[0].opinion)}`,
+            text: values[0].opinion,
+            count: values.length,
+            quotes: sortAndExtractQuotes(values),
+          }),
+        );
 
-      return {
-        topicID: topicId,
-        summary: cleanMarkdown(topicMatch?.text),
-        text: topicText,
-        count: topicOpinions.length,
-        opinions: byOpinion,
-      };
-    });
+        byOpinion.sort((a, b) => {
+          if (a.text === "Other") return 1;
+          if (b.text === "Other") return -1;
+          return b.count - a.count;
+        });
+
+        return {
+          topicID: topicId,
+          summary: cleanMarkdown(topicMatch?.text),
+          text: topicText,
+          count: keptOpinions.length,
+          opinions: byOpinion,
+        };
+      })
+      .filter((topic) => topic.opinions.length > 0);
   }
 
   /**
@@ -587,7 +640,7 @@ export function processReportData({
   const quotes = flattenQuotes(opinionsGrouped);
   const predicted = processPredicted(predictedRaw);
 
-  const topicsIdentified = (summary.sub_contents || []).length;
+  const topicsIdentified = opinionsGrouped.length;
   const topicsIdentifiedFormatted = formatNumber(topicsIdentified);
   const opinionsIdentified = opinionsGrouped
     .map((t) => t.opinions.length)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosla/sensemaking-report-builder",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Interactive HTML report builder for Cosla Python sensemaking pipeline outputs.",
   "type": "module",
   "main": "build.js",
@@ -12,7 +12,9 @@
     "build.js",
     "data.js",
     "src/**/*",
-    "README.md"
+    "schemas/**/*",
+    "README.md",
+    "smoke.js"
   ],
   "scripts": {
     "predev": "node bin/cli.js static --outputDir ./output",
@@ -21,7 +23,9 @@
     "inline": "node bin/cli.js inline",
     "build": "node bin/cli.js inline",
     "preview": "node build.js preview",
-    "github": "node build.js github"
+    "github": "node build.js github",
+    "smoke": "node smoke.js",
+    "test": "npm run smoke"
   },
   "repository": {
     "type": "git",

package/schemas/config.v1.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "config_schema_version": 1,
+  "title": "PythonReportConfig",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "title": {
+      "type": "string",
+      "title": "Report Title Override"
+    },
+    "logo": {
+      "type": "string",
+      "title": "Logo Image Filename"
+    },
+    "excluded_topics": {
+      "type": "array",
+      "title": "Excluded Topics",
+      "description": "Topic names to omit (exact match)",
+      "items": {
+        "type": "string"
+      }
+    },
+    "excluded_opinions": {
+      "type": "array",
+      "title": "Excluded Opinions",
+      "description": "Opinion names to omit (exact match)",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/smoke.js

@@ -0,0 +1,62 @@
+import { loadConfigSchema, LATEST_CONFIG_SCHEMA_VERSION } from "./data.js";
+import { runBuild } from "./build.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+async function main() {
+  const schema = loadConfigSchema(null, packageRoot);
+  assert(
+    schema.config_schema_version === LATEST_CONFIG_SCHEMA_VERSION,
+    `Expected config_schema_version ${LATEST_CONFIG_SCHEMA_VERSION}`,
+  );
+  for (const key of ["title", "logo", "excluded_topics", "excluded_opinions"]) {
+    assert(schema.properties?.[key], `Config schema missing property "${key}"`);
+  }
+
+  const explicit = loadConfigSchema(1, packageRoot);
+  assert(explicit.config_schema_version === 1, "Expected schema version 1");
+
+  let failed = false;
+  try {
+    loadConfigSchema(99, packageRoot);
+  } catch (error) {
+    failed = true;
+    assert(
+      String(error.message).includes("Unknown config schema version"),
+      `Expected clear unknown-version error, got: ${error.message}`,
+    );
+  }
+  assert(failed, "Expected unknown schema version to fail.");
+
+  const previousWrite = process.stdout.write.bind(process.stdout);
+  let captured = "";
+  process.stdout.write = (chunk) => {
+    captured += String(chunk);
+    return true;
+  };
+  try {
+    await runBuild(["node", "build.js", "config-schema"], packageRoot);
+  } finally {
+    process.stdout.write = previousWrite;
+  }
+  const printed = JSON.parse(captured);
+  assert(
+    printed.config_schema_version === 1,
+    "config-schema command did not print v1 schema",
+  );
+
+  console.log("Smoke tests passed.");
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});