cgd-validator 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# cgd-validator
+
+Validator for Clarity-Gated Document (`.cgd`) files — documents verified and annotated for safe LLM ingestion.
+
+[![npm version](https://badge.fury.io/js/cgd-validator.svg)](https://www.npmjs.com/package/cgd-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 .cgd file?
+
+A **Clarity-Gated Document** (`.cgd`) file is a markdown document that has passed epistemic verification and contains inline annotations ensuring safe interpretation by LLMs.
+
+Part of the [Clarity Gate](https://github.com/frmoretto/clarity-gate) ecosystem for epistemic quality verification.
+
+## Installation
+
+```bash
+npm install -g cgd-validator
+```
+
+## CLI Usage
+
+```bash
+# Validate a single file
+cgd-validator document.cgd
+
+# Validate multiple files
+cgd-validator docs/*.cgd
+
+# Output as JSON
+cgd-validator document.cgd --json
+
+# Quiet mode (errors only)
+cgd-validator document.cgd -q
+```
+
+## API Usage
+
+```javascript
+const { validate, isValid, detect } = require('cgd-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
+console.log(result.frontmatter); // parsed YAML frontmatter
+
+// Quick check
+if (isValid(fileContent)) {
+  console.log('Document passes validation');
+}
+
+// Detect if content is .cgd format
+if (detect(fileContent)) {
+  console.log('This appears to be a .cgd file');
+}
+```
+
+## Validation Rules
+
+### Required Elements
+- YAML frontmatter with:
+  - `clarity-gate-version`
+  - `verified-date`
+  - `verified-by`
+  - `hitl-status`
+- `## Clarity Gate Verification` section
+
+### Warnings
+- HITL status not "CONFIRMED"
+- Projections ("will be") without `*(projected)*` marker
+- Vague quantifiers without annotation
+
+## 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
+- [sot-validator](https://www.npmjs.com/package/sot-validator) - Validate .sot 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
+
+/**
+ * cgd-validator CLI
+ * Validate Clarity-Gated Document (.cgd) 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(`cgd-validator v${VERSION}`);
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  console.log(`
+cgd-validator v${VERSION}
+Validate Clarity-Gated Document (.cgd) files for LLM-safe ingestion
+
+Usage:
+  cgd-validator <file.cgd> [options]
+  cgd-validator <file.cgd> <file2.cgd> ...
+
+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:
+  cgd-validator document.cgd
+  cgd-validator docs/*.cgd --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,162 @@
+/**
+ * cgd-validator
+ * 
+ * Validator for Clarity-Gated Document (.cgd) files
+ * Documents verified and annotated for safe LLM ingestion
+ * 
+ * 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';
+
+/**
+ * Parse YAML frontmatter from CGD file
+ * @param {string} content - The file content
+ * @returns {Object|null} Parsed frontmatter or null
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+  
+  for (const line of lines) {
+    const [key, ...valueParts] = line.split(':');
+    if (key && valueParts.length) {
+      frontmatter[key.trim()] = valueParts.join(':').trim();
+    }
+  }
+  
+  return frontmatter;
+}
+
+/**
+ * Validate a Clarity-Gated Document (.cgd) 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: YAML frontmatter
+  const frontmatter = parseFrontmatter(content);
+  if (!frontmatter) {
+    errors.push({
+      code: 'MISSING_FRONTMATTER',
+      message: 'Document must contain YAML frontmatter (--- block)',
+      line: 1
+    });
+  } else {
+    // Required frontmatter fields
+    if (!frontmatter['clarity-gate-version']) {
+      errors.push({
+        code: 'MISSING_VERSION',
+        message: 'Frontmatter must contain "clarity-gate-version"',
+        line: 1
+      });
+    }
+    
+    if (!frontmatter['verified-date']) {
+      errors.push({
+        code: 'MISSING_VERIFIED_DATE',
+        message: 'Frontmatter must contain "verified-date"',
+        line: 1
+      });
+    }
+    
+    if (!frontmatter['verified-by']) {
+      errors.push({
+        code: 'MISSING_VERIFIED_BY',
+        message: 'Frontmatter must contain "verified-by"',
+        line: 1
+      });
+    }
+    
+    if (!frontmatter['hitl-status']) {
+      errors.push({
+        code: 'MISSING_HITL_STATUS',
+        message: 'Frontmatter must contain "hitl-status"',
+        line: 1
+      });
+    }
+    
+    // Warning: HITL not confirmed
+    if (frontmatter['hitl-status'] && frontmatter['hitl-status'] !== 'CONFIRMED') {
+      warnings.push({
+        code: 'HITL_NOT_CONFIRMED',
+        message: `HITL status is "${frontmatter['hitl-status']}" - should be "CONFIRMED" for full validation`,
+        line: 1
+      });
+    }
+  }
+  
+  // Required: Verification summary at end
+  if (!content.includes('## Clarity Gate Verification')) {
+    errors.push({
+      code: 'MISSING_VERIFICATION_SUMMARY',
+      message: 'Document must contain "## Clarity Gate Verification" section',
+      line: null
+    });
+  }
+  
+  // Warning: Projections without markers
+  if (content.match(/will be|will reach|will reduce/i) && !content.match(/\*\(projected/i)) {
+    warnings.push({
+      code: 'UNMARKED_PROJECTION',
+      message: 'Document contains "will be/reach/reduce" without *(projected)* marker',
+      line: null
+    });
+  }
+  
+  // Warning: Vague quantifiers without annotation
+  const vagueQuantifiers = content.match(/\b(several|many|most|some)\b(?!\s*\*\()/gi);
+  if (vagueQuantifiers && vagueQuantifiers.length > 0) {
+    warnings.push({
+      code: 'UNMARKED_VAGUE_QUANTIFIER',
+      message: `Found ${vagueQuantifiers.length} vague quantifier(s) without annotation (several, many, most, some)`,
+      line: null
+    });
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    frontmatter,
+    version: VERSION
+  };
+}
+
+/**
+ * Check if content is a valid .cgd 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 .cgd file based on content
+ * @param {string} content - The file content
+ * @returns {boolean} True if appears to be .cgd format
+ */
+function detect(content) {
+  const frontmatter = parseFrontmatter(content);
+  return frontmatter && frontmatter['clarity-gate-version'];
+}
+
+module.exports = {
+  validate,
+  isValid,
+  detect,
+  parseFrontmatter,
+  VERSION
+};

package/package.json

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