sot-validator 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# sot-validator
+
+Validator for Source of Truth (`.sot`) files — epistemic quality verification for AI-safe documentation.
+
+[![npm version](https://badge.fury.io/js/sot-validator.svg)](https://www.npmjs.com/package/sot-validator)
+[![License: CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
+
+## What is a .sot file?
+
+A **Source of Truth** (`.sot`) file is a markdown document structured to communicate explicit confidence levels for all claims, enabling readers (human or AI) to calibrate their trust appropriately.
+
+Part of the [Clarity Gate](https://github.com/frmoretto/clarity-gate) ecosystem for epistemic quality verification.
+
+## Installation
+
+```bash
+npm install -g sot-validator
+```
+
+## CLI Usage
+
+```bash
+# Validate a single file
+sot-validator project.sot
+
+# Validate multiple files
+sot-validator docs/*.sot
+
+# Output as JSON
+sot-validator project.sot --json
+
+# Quiet mode (errors only)
+sot-validator project.sot -q
+```
+
+## API Usage
+
+```javascript
+const { validate, isValid, detect } = require('sot-validator');
+
+// Full validation with errors and warnings
+const result = validate(fileContent);
+console.log(result.valid);    // boolean
+console.log(result.errors);   // array of error objects
+console.log(result.warnings); // array of warning objects
+
+// Quick check
+if (isValid(fileContent)) {
+  console.log('Document passes validation');
+}
+
+// Detect if content is .sot format
+if (detect(fileContent)) {
+  console.log('This appears to be a .sot file');
+}
+```
+
+## Validation Rules
+
+### Required Elements
+- `-- Source of Truth` header
+- `**Last Updated:**` field
+- `**Owner:**` field
+- `**Status:**` field
+- `## Verification Status` section
+
+### Warnings
+- Unqualified "VERIFIED" status (should be "with noted exceptions")
+- Estimates in Verified Data section
+- Missing staleness markers (`[STABLE]`, `[VOLATILE]`, etc.)
+
+## Related
+
+- [Clarity Gate](https://github.com/frmoretto/clarity-gate) - Pre-ingestion verification for RAG systems
+- [Source of Truth Creator](https://github.com/frmoretto/source-of-truth-creator) - Create .sot files
+- [cgd-validator](https://www.npmjs.com/package/cgd-validator) - Validate .cgd files
+
+## File Format Specification
+
+See the [SOT and CGD File Format Specification](https://github.com/frmoretto/clarity-gate/blob/main/docs/FILE_FORMAT_SPEC.md).
+
+## License
+
+CC BY 4.0 — Use freely with attribution.
+
+## Author
+
+Francesco Marinoni Moretto  
+GitHub: [@frmoretto](https://github.com/frmoretto)

package/bin/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * sot-validator CLI
+ * Validate Source of Truth (.sot) files from the command line
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validate, VERSION } = require('../index.js');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(`sot-validator v${VERSION}`);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  console.log(`
+sot-validator v${VERSION}
+Validate Source of Truth (.sot) files for epistemic quality
+
+Usage:
+  sot-validator <file.sot> [options]
+  sot-validator <file.sot> <file2.sot> ...
+
+Options:
+  -h, --help     Show this help message
+  -v, --version  Show version number
+  -q, --quiet    Only output errors (no warnings)
+  --json         Output results as JSON
+
+Examples:
+  sot-validator project.sot
+  sot-validator docs/*.sot --json
+
+Part of the Clarity Gate ecosystem:
+  https://github.com/frmoretto/clarity-gate
+
+File Format Specification:
+  https://github.com/frmoretto/clarity-gate/docs/FILE_FORMAT_SPEC.md
+`);
+  process.exit(0);
+}
+
+const quiet = args.includes('-q') || args.includes('--quiet');
+const json = args.includes('--json');
+const files = args.filter(a => !a.startsWith('-'));
+
+if (files.length === 0) {
+  console.error('Error: No files specified');
+  process.exit(1);
+}
+
+let hasErrors = false;
+const results = [];
+
+for (const file of files) {
+  const filePath = path.resolve(file);
+  
+  if (!fs.existsSync(filePath)) {
+    console.error(`Error: File not found: ${file}`);
+    hasErrors = true;
+    continue;
+  }
+  
+  const content = fs.readFileSync(filePath, 'utf8');
+  const result = validate(content);
+  result.file = file;
+  results.push(result);
+  
+  if (!result.valid) {
+    hasErrors = true;
+  }
+  
+  if (!json) {
+    if (result.valid && result.warnings.length === 0) {
+      console.log(`✓ ${file}: PASS`);
+    } else if (result.valid) {
+      console.log(`⚠ ${file}: PASS with warnings`);
+      if (!quiet) {
+        result.warnings.forEach(w => {
+          console.log(`  Warning: ${w.message}`);
+        });
+      }
+    } else {
+      console.log(`✗ ${file}: FAIL`);
+      result.errors.forEach(e => {
+        console.log(`  Error: ${e.message}`);
+      });
+      if (!quiet) {
+        result.warnings.forEach(w => {
+          console.log(`  Warning: ${w.message}`);
+        });
+      }
+    }
+  }
+}
+
+if (json) {
+  console.log(JSON.stringify(results, null, 2));
+}
+
+process.exit(hasErrors ? 1 : 0);

package/index.js

@@ -0,0 +1,131 @@
+/**
+ * sot-validator
+ * 
+ * Validator for Source of Truth (.sot) files
+ * Epistemic quality verification for AI-safe documentation
+ * 
+ * Part of the Clarity Gate ecosystem:
+ * - .sot (Source of Truth) - Authoritative reference documents
+ * - .cgd (Clarity-Gated Document) - Verified for LLM ingestion
+ * 
+ * @see https://github.com/frmoretto/clarity-gate
+ * @license CC-BY-4.0
+ */
+
+const VERSION = '0.1.0';
+
+/**
+ * Validate a Source of Truth (.sot) file
+ * @param {string} content - The file content to validate
+ * @returns {ValidationResult} Validation result with errors and warnings
+ */
+function validate(content) {
+  const errors = [];
+  const warnings = [];
+  
+  // Required: Header block
+  if (!content.includes('-- Source of Truth')) {
+    errors.push({
+      code: 'MISSING_HEADER',
+      message: 'Document must contain "-- Source of Truth" header',
+      line: 1
+    });
+  }
+  
+  // Required: Last Updated
+  if (!content.match(/\*\*Last Updated:\*\*/)) {
+    errors.push({
+      code: 'MISSING_DATE',
+      message: 'Document must contain "**Last Updated:**" field',
+      line: null
+    });
+  }
+  
+  // Required: Owner
+  if (!content.match(/\*\*Owner:\*\*/)) {
+    errors.push({
+      code: 'MISSING_OWNER',
+      message: 'Document must contain "**Owner:**" field',
+      line: null
+    });
+  }
+  
+  // Required: Status
+  if (!content.match(/\*\*Status:\*\*/)) {
+    errors.push({
+      code: 'MISSING_STATUS',
+      message: 'Document must contain "**Status:**" field',
+      line: null
+    });
+  }
+  
+  // Required: Verification Status table
+  if (!content.includes('## Verification Status')) {
+    errors.push({
+      code: 'MISSING_VERIFICATION_TABLE',
+      message: 'Document must contain "## Verification Status" section',
+      line: null
+    });
+  }
+  
+  // Warning: Status says VERIFIED without qualification
+  if (content.match(/Status:\*\*\s*VERIFIED\s*$/m)) {
+    warnings.push({
+      code: 'UNQUALIFIED_VERIFIED',
+      message: 'Status "VERIFIED" should be qualified (e.g., "with noted exceptions")',
+      line: null
+    });
+  }
+  
+  // Warning: Estimates in Verified Data section
+  const verifiedDataSection = content.match(/## Verified Data[\s\S]*?(?=##|$)/);
+  if (verifiedDataSection && verifiedDataSection[0].match(/~\d|estimated|approximately/i)) {
+    warnings.push({
+      code: 'ESTIMATES_IN_VERIFIED',
+      message: 'Estimates found in Verified Data section - move to Estimates section',
+      line: null
+    });
+  }
+  
+  // Warning: Missing staleness markers
+  if (content.includes('## Verified Data') && !content.match(/\[STABLE\]|\[VOLATILE\]|\[CHECK BEFORE CITING\]|\[SNAPSHOT\]/)) {
+    warnings.push({
+      code: 'MISSING_STALENESS',
+      message: 'Verified Data should include staleness markers ([STABLE], [VOLATILE], etc.)',
+      line: null
+    });
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    version: VERSION
+  };
+}
+
+/**
+ * Check if content is a valid .sot file
+ * @param {string} content - The file content to check
+ * @returns {boolean} True if valid
+ */
+function isValid(content) {
+  return validate(content).valid;
+}
+
+/**
+ * Detect if a file is a .sot file based on content
+ * @param {string} content - The file content
+ * @returns {boolean} True if appears to be .sot format
+ */
+function detect(content) {
+  return content.includes('-- Source of Truth') && 
+         content.includes('## Verification Status');
+}
+
+module.exports = {
+  validate,
+  isValid,
+  detect,
+  VERSION
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "sot-validator",
+  "version": "0.1.0",
+  "description": "Validator for Source of Truth (.sot) files - epistemic quality verification for AI-safe documentation",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "sot-validator": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Tests coming soon\" && exit 0"
+  },
+  "keywords": [
+    "sot",
+    "source-of-truth",
+    "validator",
+    "epistemic",
+    "ai-safety",
+    "rag",
+    "documentation",
+    "clarity-gate",
+    "verification"
+  ],
+  "author": "Francesco Marinoni Moretto",
+  "license": "CC-BY-4.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/frmoretto/sot-validator"
+  },
+  "homepage": "https://github.com/frmoretto/clarity-gate",
+  "bugs": {
+    "url": "https://github.com/frmoretto/clarity-gate/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}