@nforma.ai/nforma 0.2.1

package/bin/extractFormalExpected.cjs

@@ -0,0 +1,104 @@
+/**
+ * Formal expected value extraction for P->F residual layer
+ * Parses formal_ref strings and loads parameter values from spec files
+ * Fail-open: returns null on any error (missing file, bad parse, etc.)
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Parse a formal_ref string into its components
+ * Formats:
+ *   "spec:{module}/{file}:{param}" -> { type: 'spec', module, file, param }
+ *   "requirement:{id}" -> { type: 'requirement', id }
+ *   null/invalid -> null
+ * @param {string} formalRef
+ * @returns {object|null}
+ */
+function parseFormalRef(formalRef) {
+  if (!formalRef || typeof formalRef !== 'string') return null;
+
+  if (formalRef.startsWith('requirement:')) {
+    return { type: 'requirement', id: formalRef.slice('requirement:'.length) };
+  }
+
+  if (formalRef.startsWith('spec:')) {
+    const rest = formalRef.slice('spec:'.length);
+    // Format: module/file:param
+    const colonIdx = rest.lastIndexOf(':');
+    if (colonIdx === -1) {
+      // No param key — invariant reference (e.g., "spec:safety/invariant-consistency")
+      return { type: 'spec', path: rest, param: null };
+    }
+    const filePath = rest.slice(0, colonIdx);
+    const param = rest.slice(colonIdx + 1);
+    return { type: 'spec', path: filePath, param: param || null };
+  }
+
+  return null;
+}
+
+/**
+ * Extract formal expected value from a spec file
+ * Supports .cfg files (line-based key=value) and .json files
+ * @param {string} formalRef - Formal reference string
+ * @param {object} [options]
+ * @param {string} [options.specDir] - Override default spec directory (for testing)
+ * @returns {*} The parameter value, or null if not found
+ */
+function extractFormalExpected(formalRef, options = {}) {
+  const parsed = parseFormalRef(formalRef);
+  if (!parsed) return null;
+
+  // Requirements are text, not numeric — return null
+  if (parsed.type === 'requirement') return null;
+
+  // Spec without param key — invariant reference, no extractable value
+  if (parsed.type === 'spec' && !parsed.param) return null;
+
+  const specDir = options.specDir || path.resolve(process.cwd(), '.planning/formal/spec');
+  const filePath = path.join(specDir, parsed.path);
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // JSON files
+    if (filePath.endsWith('.json')) {
+      const data = JSON.parse(content);
+      const val = data[parsed.param];
+      return val !== undefined ? val : null;
+    }
+
+    // CFG files (TLA+ config format: key = value)
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      // Skip comments and empty lines
+      if (!trimmed || trimmed.startsWith('\\*') || trimmed.startsWith('SPECIFICATION') ||
+          trimmed.startsWith('CONSTANTS') || trimmed.startsWith('SYMMETRY') ||
+          trimmed.startsWith('INVARIANT') || trimmed.startsWith('PROPERTY') ||
+          trimmed.startsWith('CHECK_DEADLOCK')) {
+        continue;
+      }
+      // Match key = value patterns
+      const match = trimmed.match(/^(\w+)\s*=\s*(.+)$/);
+      if (match && match[1] === parsed.param) {
+        const rawVal = match[2].trim();
+        // Try to parse as number
+        const num = Number(rawVal);
+        if (!isNaN(num) && rawVal !== '') return num;
+        // Return as string
+        return rawVal;
+      }
+    }
+
+    return null; // Param not found in file
+  } catch {
+    // Fail-open: file not found, parse error, etc.
+    return null;
+  }
+}
+
+module.exports = { extractFormalExpected, parseFormalRef };

package/bin/fingerprint-drift.cjs

@@ -0,0 +1,24 @@
+const crypto = require('crypto');
+
+/**
+ * Generate deterministic fingerprint for a drift using formal parameter key
+ * Fingerprint depends only on the parameter key, not measured values or timestamps
+ *
+ * @param {Object} drift - Drift object with formal_parameter_key and other optional fields
+ * @returns {string} - 16-char hex fingerprint
+ * @throws {Error} - If formal_parameter_key is missing or empty
+ */
+function fingerprintDrift(drift) {
+  // Validate that formal_parameter_key exists and is non-empty
+  if (!drift.formal_parameter_key || typeof drift.formal_parameter_key !== 'string' || drift.formal_parameter_key.trim() === '') {
+    throw new Error('formal_parameter_key required (non-empty string)');
+  }
+
+  // Deterministic hash of the formal parameter key
+  return crypto.createHash('sha256')
+    .update(drift.formal_parameter_key)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+module.exports = { fingerprintDrift };

package/bin/fingerprint-issue.cjs

@@ -0,0 +1,46 @@
+const crypto = require('crypto');
+
+/**
+ * Normalize and hash an error message
+ * Strips timestamps, line numbers, and lowercases for stable hashing
+ *
+ * @param {string} msg - Error message text
+ * @returns {string} - 16-char hex hash
+ */
+function hashMessage(msg) {
+  const normalized = (msg || '')
+    .replace(/\d{4}-\d{2}-\d{2}T[\d:.Z]+/g, 'TIMESTAMP') // ISO8601 timestamps
+    .replace(/:\d+/g, ':LINE')                             // Line numbers
+    .toLowerCase()
+    .trim();
+
+  return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+
+/**
+ * Generate deterministic fingerprint for an issue using hierarchical strategy:
+ * exception_type -> function_name -> message_hash
+ *
+ * @param {Object} issue - Issue object with optional exception_type, function_name, message
+ * @returns {string} - 16-char hex fingerprint
+ */
+function fingerprintIssue(issue) {
+  // Normalize exception type
+  const exceptionType = (issue.exception_type || 'unknown').toLowerCase();
+
+  // Normalize function name (replace non-alphanumeric with underscore)
+  const functionName = (issue.function_name || 'unknown')
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_');
+
+  // Hash the message
+  const msgHash = hashMessage(issue.message);
+
+  // Combine components with colon separator
+  const combined = `${exceptionType}:${functionName}:${msgHash}`;
+
+  // Final deterministic hash
+  return crypto.createHash('sha256').update(combined).digest('hex').slice(0, 16);
+}
+
+module.exports = { fingerprintIssue, hashMessage };

package/bin/formal-core.cjs

@@ -0,0 +1,519 @@
+'use strict';
+
+/**
+ * Pure data functions for formal verification browsing.
+ * No blessed dependency — all functions are testable in isolation.
+ * Consumers: bin/nForma.cjs (blessed TUI)
+ *
+ * Data sources (project-relative paths via basePath):
+ *   .planning/formal/model-registry.json     — formal model inventory
+ *   .planning/formal/traceability-matrix.json — requirement-property links
+ *   .planning/formal/unit-test-coverage.json  — test coverage sidecar
+ *   .planning/formal/state-space-report.json  — variable domains & risk
+ *   .planning/formal/check-results.ndjson     — verification results
+ *   .planning/formal/requirements.json        — requirement definitions
+ *   .planning/formal/tla/*.tla                — TLA+ source files
+ *   .planning/formal/alloy/*.als              — Alloy source files
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Data loaders (fail-open: return empty on missing/corrupt files)
+// ---------------------------------------------------------------------------
+
+function loadJSON(basePath, relPath) {
+  const p = path.join(basePath || process.cwd(), relPath);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+function loadModelRegistry(basePath) {
+  return loadJSON(basePath, '.planning/formal/model-registry.json') || { models: {} };
+}
+
+function loadTraceabilityMatrix(basePath) {
+  return loadJSON(basePath, '.planning/formal/traceability-matrix.json') || { requirements: {}, properties: {} };
+}
+
+function loadUnitTestCoverage(basePath) {
+  return loadJSON(basePath, '.planning/formal/unit-test-coverage.json') || { requirements: {} };
+}
+
+function loadStateSpaceReport(basePath) {
+  return loadJSON(basePath, '.planning/formal/state-space-report.json') || { models: {} };
+}
+
+function loadRequirements(basePath) {
+  return loadJSON(basePath, '.planning/formal/requirements.json') || { requirements: [] };
+}
+
+// ---------------------------------------------------------------------------
+// TLA+ / Alloy source parsers (lightweight — extract variables & properties)
+// ---------------------------------------------------------------------------
+
+function parseTLAVariables(content) {
+  const vars = [];
+  const lines = content.split('\n');
+  let inVarBlock = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^VARIABLES?\b/.test(line.trim())) {
+      inVarBlock = true;
+      // Variables may be on same line: VARIABLES a, b, c
+      const inline = line.replace(/^VARIABLES?\s*/, '').trim();
+      if (inline) {
+        for (const v of inline.split(',')) {
+          const name = v.trim().replace(/\\.*$/, '').trim();
+          if (name) vars.push({ name, comment: extractInlineComment(line) });
+        }
+      }
+      continue;
+    }
+    if (inVarBlock) {
+      if (line.trim() === '' || /^[A-Z]/.test(line.trim()) && !/^\s/.test(line)) {
+        // End of variable block (blank line or new definition)
+        if (!/^\s/.test(line) && line.trim() !== '') inVarBlock = false;
+        continue;
+      }
+      for (const v of line.split(',')) {
+        const name = v.trim().replace(/\\.*$/, '').trim();
+        if (name) vars.push({ name, comment: extractInlineComment(line) });
+      }
+    }
+  }
+  return vars;
+}
+
+function extractInlineComment(line) {
+  const match = line.match(/\\[*]\s*(.+)$/);
+  return match ? match[1].trim() : null;
+}
+
+function parseTLAProperties(content) {
+  const props = [];
+  const lines = content.split('\n');
+  let pendingReqs = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    // Collect @requirement annotations
+    const reqMatch = line.match(/@requirement\s+(.+)/);
+    if (reqMatch) {
+      pendingReqs.push(...reqMatch[1].split(/[,\s]+/).filter(Boolean));
+      continue;
+    }
+    // Property definition: Name ==
+    const propMatch = line.match(/^(\w+)\s*==/);
+    if (propMatch) {
+      const name = propMatch[1];
+      // Skip infrastructure definitions
+      if (!['vars', 'Init', 'Next', 'Spec', 'Fairness', 'Symmetry'].includes(name)) {
+        props.push({
+          name,
+          requirements: pendingReqs.length > 0 ? [...pendingReqs] : [],
+          line: i + 1,
+        });
+      }
+      pendingReqs = [];
+    } else if (!line.startsWith('\\*') && !line.startsWith('(*') && line !== '') {
+      // Non-comment, non-empty line clears pending annotations
+      if (!reqMatch) pendingReqs = [];
+    }
+  }
+  return props;
+}
+
+function parseAlloyConstructs(content) {
+  const constructs = [];
+  const lines = content.split('\n');
+  let pendingReqs = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const reqMatch = line.match(/@requirement\s+(.+)/);
+    if (reqMatch) {
+      pendingReqs.push(...reqMatch[1].split(/[,\s]+/).filter(Boolean));
+      continue;
+    }
+    // Alloy construct: sig, fact, assert, pred, fun, check, run
+    const cMatch = line.match(/^(sig|fact|assert|pred|fun|check|run)\s+(\w+)/);
+    if (cMatch) {
+      constructs.push({
+        kind: cMatch[1],
+        name: cMatch[2],
+        requirements: pendingReqs.length > 0 ? [...pendingReqs] : [],
+        line: i + 1,
+      });
+      pendingReqs = [];
+    }
+  }
+  return constructs;
+}
+
+function parseAlloySigs(content) {
+  const sigs = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const sigMatch = line.match(/^(?:abstract\s+|one\s+|lone\s+)?sig\s+(\w+)(?:\s+extends\s+(\w+))?/);
+    if (sigMatch) {
+      const fields = [];
+      // Parse fields in the sig body
+      for (let j = i + 1; j < lines.length; j++) {
+        const fl = lines[j].trim();
+        if (fl.startsWith('}')) break;
+        const fieldMatch = fl.match(/^(\w+)\s*:\s*(.+?)(?:,|$)/);
+        if (fieldMatch) {
+          fields.push({ name: fieldMatch[1], type: fieldMatch[2].trim().replace(/,\s*$/, '') });
+        }
+      }
+      sigs.push({
+        name: sigMatch[1],
+        extends: sigMatch[2] || null,
+        fields,
+        line: i + 1,
+      });
+    }
+  }
+  return sigs;
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a comprehensive model summary from all data sources.
+ * Returns array of model objects with parsed details.
+ */
+function buildModelIndex(basePath) {
+  const registry = loadModelRegistry(basePath);
+  const stateSpace = loadStateSpaceReport(basePath);
+  const matrix = loadTraceabilityMatrix(basePath);
+  const base = basePath || process.cwd();
+
+  const models = [];
+
+  for (const [modelPath, entry] of Object.entries(registry.models || {})) {
+    const absPath = path.join(base, modelPath);
+    const exists = fs.existsSync(absPath);
+    const ext = path.extname(modelPath).toLowerCase();
+    const formalism = ext === '.tla' ? 'TLA+' : ext === '.als' ? 'Alloy' : ext === '.pm' ? 'PRISM' : 'Unknown';
+
+    let variables = [];
+    let properties = [];
+    let constructs = [];
+    let sigs = [];
+
+    if (exists) {
+      const content = fs.readFileSync(absPath, 'utf8');
+      if (formalism === 'TLA+') {
+        variables = parseTLAVariables(content);
+        properties = parseTLAProperties(content);
+      } else if (formalism === 'Alloy') {
+        constructs = parseAlloyConstructs(content);
+        sigs = parseAlloySigs(content);
+      }
+    }
+
+    // State-space info
+    const ssEntry = (stateSpace.models || {})[modelPath] || null;
+
+    // Properties from traceability matrix
+    const matrixProps = [];
+    for (const [key, prop] of Object.entries(matrix.properties || {})) {
+      if (prop.model_file === modelPath) {
+        matrixProps.push(prop);
+      }
+    }
+
+    models.push({
+      path: modelPath,
+      formalism,
+      exists,
+      description: entry.description || '',
+      version: entry.version || null,
+      requirements: entry.requirements || [],
+      variables,
+      properties,       // TLA+ properties
+      constructs,       // Alloy constructs
+      sigs,             // Alloy sigs
+      stateSpace: ssEntry,
+      matrixProperties: matrixProps,
+    });
+  }
+
+  return models;
+}
+
+/**
+ * Build a test coverage index: requirement → test cases.
+ */
+function buildTestIndex(basePath) {
+  const utc = loadUnitTestCoverage(basePath);
+  const reqs = loadRequirements(basePath);
+  const reqMap = {};
+
+  for (const r of (reqs.requirements || [])) {
+    reqMap[r.id] = {
+      id: r.id,
+      text: r.text || '',
+      category: r.category || 'Uncategorized',
+      status: r.status || 'Unknown',
+      covered: false,
+      testCases: [],
+    };
+  }
+
+  for (const [reqId, entry] of Object.entries(utc.requirements || {})) {
+    if (!reqMap[reqId]) {
+      reqMap[reqId] = { id: reqId, text: '', category: 'Unknown', status: 'Unknown', covered: false, testCases: [] };
+    }
+    reqMap[reqId].covered = entry.covered || false;
+    reqMap[reqId].testCases = (entry.test_cases || []).map(tc => ({
+      file: tc.test_file || '',
+      name: tc.test_name || '',
+    }));
+  }
+
+  return reqMap;
+}
+
+/**
+ * Build a variable index across all models.
+ * Returns array of { variable, model, domain, cardinality, bounded, risk }.
+ */
+function buildVariableIndex(basePath) {
+  const models = buildModelIndex(basePath);
+  const stateSpace = loadStateSpaceReport(basePath);
+  const variables = [];
+
+  for (const model of models) {
+    if (model.formalism === 'TLA+') {
+      const ssVars = ((stateSpace.models || {})[model.path] || {}).variables || [];
+      const ssMap = {};
+      for (const sv of ssVars) { ssMap[sv.name] = sv; }
+
+      for (const v of model.variables) {
+        const sv = ssMap[v.name] || {};
+        variables.push({
+          name: v.name,
+          model: model.path,
+          formalism: 'TLA+',
+          comment: v.comment,
+          domain: sv.domain || null,
+          cardinality: sv.cardinality || null,
+          bounded: sv.bounded != null ? sv.bounded : null,
+        });
+      }
+    } else if (model.formalism === 'Alloy') {
+      for (const sig of model.sigs) {
+        for (const field of sig.fields) {
+          variables.push({
+            name: `${sig.name}.${field.name}`,
+            model: model.path,
+            formalism: 'Alloy',
+            comment: null,
+            domain: field.type,
+            cardinality: null,
+            bounded: true, // Alloy is always bounded
+          });
+        }
+      }
+    }
+  }
+
+  return variables;
+}
+
+/**
+ * Build an interconnection graph: nodes (reqs, models, tests, properties)
+ * and edges showing how they link together.
+ */
+function buildInterconnectionGraph(basePath) {
+  const models = buildModelIndex(basePath);
+  const testIndex = buildTestIndex(basePath);
+  const matrix = loadTraceabilityMatrix(basePath);
+
+  const nodes = { requirements: {}, models: {}, properties: {}, tests: {} };
+  const edges = [];
+
+  // Requirements
+  for (const [reqId, entry] of Object.entries(testIndex)) {
+    nodes.requirements[reqId] = {
+      type: 'requirement',
+      id: reqId,
+      text: entry.text,
+      category: entry.category,
+      status: entry.status,
+    };
+  }
+
+  // Models + edges to requirements
+  for (const model of models) {
+    const shortPath = path.basename(model.path);
+    nodes.models[model.path] = {
+      type: 'model',
+      id: model.path,
+      shortName: shortPath,
+      formalism: model.formalism,
+      varCount: model.variables.length + model.sigs.reduce((n, s) => n + s.fields.length, 0),
+      propCount: model.properties.length + model.constructs.length,
+      riskLevel: model.stateSpace ? model.stateSpace.risk_level : null,
+    };
+
+    for (const reqId of model.requirements) {
+      edges.push({ from: reqId, to: model.path, type: 'req-model' });
+    }
+
+    // Properties → requirements
+    for (const prop of model.properties) {
+      const propKey = `${model.path}::${prop.name}`;
+      nodes.properties[propKey] = {
+        type: 'property',
+        id: propKey,
+        name: prop.name,
+        model: model.path,
+      };
+      for (const reqId of prop.requirements) {
+        edges.push({ from: reqId, to: propKey, type: 'req-property' });
+      }
+    }
+    for (const c of model.constructs) {
+      const cKey = `${model.path}::${c.name}`;
+      nodes.properties[cKey] = {
+        type: 'property',
+        id: cKey,
+        name: c.name,
+        kind: c.kind,
+        model: model.path,
+      };
+      for (const reqId of c.requirements) {
+        edges.push({ from: reqId, to: cKey, type: 'req-property' });
+      }
+    }
+  }
+
+  // Tests → requirements
+  for (const [reqId, entry] of Object.entries(testIndex)) {
+    for (const tc of entry.testCases) {
+      const testKey = `${tc.file}::${tc.name}`;
+      if (!nodes.tests[testKey]) {
+        nodes.tests[testKey] = { type: 'test', id: testKey, file: tc.file, name: tc.name };
+      }
+      edges.push({ from: reqId, to: testKey, type: 'req-test' });
+    }
+  }
+
+  return { nodes, edges };
+}
+
+/**
+ * Build a summary dashboard of the formal verification ecosystem.
+ */
+function buildFormalSummary(basePath) {
+  const models = buildModelIndex(basePath);
+  const testIndex = buildTestIndex(basePath);
+  const stateSpace = loadStateSpaceReport(basePath);
+
+  const tlaModels = models.filter(m => m.formalism === 'TLA+');
+  const alloyModels = models.filter(m => m.formalism === 'Alloy');
+
+  // Count variables
+  let totalVars = 0;
+  let unboundedVars = 0;
+  for (const m of models) {
+    if (m.formalism === 'TLA+') totalVars += m.variables.length;
+    if (m.formalism === 'Alloy') totalVars += m.sigs.reduce((n, s) => n + s.fields.length, 0);
+  }
+  const ssModels = Object.values(stateSpace.models || {});
+  for (const ss of ssModels) {
+    for (const v of (ss.variables || [])) {
+      if (!v.bounded) unboundedVars++;
+    }
+  }
+
+  // Count properties
+  let totalProps = 0;
+  let annotatedProps = 0;
+  for (const m of models) {
+    for (const p of m.properties) {
+      totalProps++;
+      if (p.requirements.length > 0) annotatedProps++;
+    }
+    for (const c of m.constructs) {
+      totalProps++;
+      if (c.requirements.length > 0) annotatedProps++;
+    }
+  }
+
+  // Risk distribution
+  const byRisk = { MINIMAL: 0, LOW: 0, MODERATE: 0, HIGH: 0 };
+  for (const m of models) {
+    if (m.stateSpace && m.stateSpace.risk_level) {
+      byRisk[m.stateSpace.risk_level] = (byRisk[m.stateSpace.risk_level] || 0) + 1;
+    }
+  }
+
+  // Test coverage
+  const totalReqs = Object.keys(testIndex).length;
+  const coveredReqs = Object.values(testIndex).filter(t => t.covered).length;
+  const totalTests = Object.values(testIndex).reduce((n, t) => n + t.testCases.length, 0);
+
+  // All unique requirements across models
+  const allModelReqs = new Set();
+  for (const m of models) {
+    for (const r of m.requirements) allModelReqs.add(r);
+  }
+
+  return {
+    models: {
+      total: models.length,
+      tla: tlaModels.length,
+      alloy: alloyModels.length,
+      other: models.length - tlaModels.length - alloyModels.length,
+    },
+    variables: {
+      total: totalVars,
+      unbounded: unboundedVars,
+    },
+    properties: {
+      total: totalProps,
+      annotated: annotatedProps,
+      unannotated: totalProps - annotatedProps,
+    },
+    risk: byRisk,
+    coverage: {
+      totalReqs,
+      coveredReqs,
+      totalTests,
+      modelLinkedReqs: allModelReqs.size,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  loadModelRegistry,
+  loadTraceabilityMatrix,
+  loadUnitTestCoverage,
+  loadStateSpaceReport,
+  loadRequirements,
+  parseTLAVariables,
+  parseTLAProperties,
+  parseAlloyConstructs,
+  parseAlloySigs,
+  buildModelIndex,
+  buildTestIndex,
+  buildVariableIndex,
+  buildInterconnectionGraph,
+  buildFormalSummary,
+};
+
+module.exports._pure = module.exports;