@cosla/sensemaking-report-builder 0.1.1 → 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

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");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosla/sensemaking-report-builder",
-  "version": "0.1.1",
+  "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);
+});