@plures/praxis 1.1.3 → 1.2.10

package/dist/node/chunk-WZ6B3LZ6.js

@@ -0,0 +1,638 @@
+// src/decision-ledger/types.ts
+function isContract(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  const contract = obj;
+  return typeof contract.ruleId === "string" && typeof contract.behavior === "string" && Array.isArray(contract.examples) && contract.examples.length > 0 && contract.examples.every(
+    (ex) => typeof ex === "object" && ex !== null && typeof ex.given === "string" && typeof ex.when === "string" && typeof ex.then === "string"
+  ) && Array.isArray(contract.invariants) && contract.invariants.every((inv) => typeof inv === "string");
+}
+function defineContract(options) {
+  if (options.examples.length === 0) {
+    throw new Error("Contract must have at least one example");
+  }
+  if (options.assumptions) {
+    for (const assumption of options.assumptions) {
+      if (assumption.confidence < 0 || assumption.confidence > 1) {
+        throw new Error(
+          `Assumption '${assumption.id}' has invalid confidence value ${assumption.confidence}. Must be between 0.0 and 1.0`
+        );
+      }
+    }
+  }
+  return {
+    ruleId: options.ruleId,
+    behavior: options.behavior,
+    examples: options.examples,
+    invariants: options.invariants,
+    assumptions: options.assumptions,
+    references: options.references,
+    version: options.version || "1.0.0",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function getContract(meta) {
+  if (!meta || !meta.contract) {
+    return void 0;
+  }
+  if (isContract(meta.contract)) {
+    return meta.contract;
+  }
+  return void 0;
+}
+function getContractFromDescriptor(descriptor) {
+  if (!descriptor) {
+    return void 0;
+  }
+  if (descriptor.contract && isContract(descriptor.contract)) {
+    return descriptor.contract;
+  }
+  return getContract(descriptor.meta);
+}
+
+// src/decision-ledger/logic-ledger.ts
+import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import path from "path";
+async function writeLogicLedgerEntry(contract, options) {
+  const rootDir = options.rootDir;
+  const ledgerId = normalizeRuleId(contract.ruleId);
+  const ledgerDir = path.join(rootDir, "logic-ledger", ledgerId);
+  await fs.mkdir(ledgerDir, { recursive: true });
+  const latestPath = path.join(ledgerDir, "LATEST.json");
+  const latest = await readJson(latestPath, null);
+  const nextVersion = latest ? latest.version + 1 : 1;
+  const entry = {
+    ruleId: contract.ruleId,
+    version: nextVersion,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    canonicalBehavior: {
+      behavior: contract.behavior,
+      examples: contract.examples,
+      invariants: contract.invariants
+    },
+    assumptions: contract.assumptions ?? [],
+    artifacts: {
+      contractPresent: true,
+      testsPresent: options.testsPresent ?? false,
+      specPresent: options.specPresent ?? false
+    },
+    drift: computeDrift(latest, contract)
+  };
+  const versionFile = path.join(ledgerDir, `v${String(nextVersion).padStart(4, "0")}.json`);
+  await fs.writeFile(versionFile, JSON.stringify(entry, null, 2));
+  await fs.writeFile(latestPath, JSON.stringify(entry, null, 2));
+  await updateIndex(rootDir, contract.ruleId, path.relative(rootDir, ledgerDir));
+  return entry;
+}
+function computeDrift(previous, contract) {
+  if (!previous) {
+    return {
+      changeSummary: "initial",
+      assumptionsInvalidated: [],
+      assumptionsRevised: [],
+      conflicts: []
+    };
+  }
+  const conflicts = [];
+  const previousBehavior = JSON.stringify(previous.canonicalBehavior);
+  const nextBehavior = JSON.stringify({
+    behavior: contract.behavior,
+    examples: contract.examples,
+    invariants: contract.invariants
+  });
+  if (previousBehavior !== nextBehavior) {
+    conflicts.push("behavior-changed");
+  }
+  const prevAssumptions = new Map(previous.assumptions.map((a) => [a.id, a]));
+  const assumptionsInvalidated = [];
+  const assumptionsRevised = [];
+  for (const assumption of contract.assumptions ?? []) {
+    const prior = prevAssumptions.get(assumption.id);
+    if (!prior) {
+      continue;
+    }
+    if (prior.statement !== assumption.statement || prior.status !== assumption.status) {
+      assumptionsRevised.push(assumption.id);
+    }
+  }
+  for (const prior of previous.assumptions) {
+    const current = (contract.assumptions ?? []).find((a) => a.id === prior.id);
+    if (!current || current.status === "invalidated") {
+      assumptionsInvalidated.push(prior.id);
+    }
+  }
+  return {
+    changeSummary: conflicts.length > 0 ? "updated" : "no-change",
+    assumptionsInvalidated,
+    assumptionsRevised,
+    conflicts
+  };
+}
+async function updateIndex(rootDir, ruleId, ledgerDir) {
+  const indexPath = path.join(rootDir, "logic-ledger", "index.json");
+  const index = await readJson(indexPath, { byRuleId: {} });
+  index.byRuleId[ruleId] = ledgerDir.replace(/\\/g, "/");
+  await fs.mkdir(path.dirname(indexPath), { recursive: true });
+  await fs.writeFile(indexPath, JSON.stringify(index, null, 2));
+}
+function normalizeRuleId(ruleId) {
+  const hash = createHash("sha256").update(ruleId).digest("hex").slice(0, 6);
+  return `${ruleId.replace(/[^a-zA-Z0-9_-]/g, "-")}-${hash}`.toLowerCase();
+}
+async function readJson(filePath, fallback) {
+  try {
+    const data = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return fallback;
+  }
+}
+
+// src/decision-ledger/scanner.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+async function scanRepository(options) {
+  const startTime = Date.now();
+  const { rootDir, scanTests = true, scanSpecs = true, maxDepth = 10 } = options;
+  const normalizedRoot = path2.resolve(rootDir);
+  try {
+    const stats = await fs2.stat(normalizedRoot);
+    if (!stats.isDirectory()) {
+      throw new Error(`Path is not a directory: ${normalizedRoot}`);
+    }
+  } catch (error) {
+    throw new Error(`Invalid root directory: ${normalizedRoot} - ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const rules = [];
+  const constraints = [];
+  const testFiles = /* @__PURE__ */ new Map();
+  const specFiles = /* @__PURE__ */ new Map();
+  const scanWarnings = [];
+  let filesScanned = 0;
+  const implFiles = await findFiles(
+    normalizedRoot,
+    {
+      include: options.include || ["**/*.ts", "**/*.js"],
+      exclude: options.exclude || [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/*.test.ts",
+        "**/*.test.js",
+        "**/*.spec.ts",
+        "**/*.spec.js"
+      ],
+      maxDepth
+    },
+    scanWarnings
+  );
+  for (const file of implFiles) {
+    filesScanned++;
+    const stats = await fs2.stat(file);
+    const maxFileSize = 10 * 1024 * 1024;
+    if (stats.size > maxFileSize) {
+      scanWarnings.push(`Skipping large file (${(stats.size / 1024 / 1024).toFixed(2)} MB): ${file}`);
+      continue;
+    }
+    const content = await fs2.readFile(file, "utf-8");
+    const discoveredRules = await extractRulesFromFile(file, content);
+    const discoveredConstraints = await extractConstraintsFromFile(file, content);
+    rules.push(...discoveredRules);
+    constraints.push(...discoveredConstraints);
+  }
+  if (scanTests) {
+    const testFileList = await findFiles(
+      normalizedRoot,
+      {
+        include: ["**/*.test.ts", "**/*.test.js", "**/*.spec.ts", "**/*.spec.js"],
+        exclude: ["**/node_modules/**", "**/dist/**", "**/build/**"],
+        maxDepth
+      },
+      scanWarnings
+    );
+    for (const testFile of testFileList) {
+      filesScanned++;
+      const stats = await fs2.stat(testFile);
+      const maxFileSize = 10 * 1024 * 1024;
+      if (stats.size > maxFileSize) {
+        scanWarnings.push(`Skipping large test file (${(stats.size / 1024 / 1024).toFixed(2)} MB): ${testFile}`);
+        continue;
+      }
+      const content = await fs2.readFile(testFile, "utf-8");
+      const mappings = await mapTestsToRules(testFile, content, rules);
+      for (const [ruleId, filePath] of mappings) {
+        if (!testFiles.has(ruleId)) {
+          testFiles.set(ruleId, []);
+        }
+        testFiles.get(ruleId).push(filePath);
+      }
+    }
+  }
+  if (scanSpecs) {
+    const specFileList = await findFiles(
+      normalizedRoot,
+      {
+        include: ["**/*.tla", "**/*.md", "**/spec/**/*.ts"],
+        exclude: ["**/node_modules/**", "**/dist/**", "**/build/**"],
+        maxDepth
+      },
+      scanWarnings
+    );
+    for (const specFile of specFileList) {
+      filesScanned++;
+      const stats = await fs2.stat(specFile);
+      const maxFileSize = 10 * 1024 * 1024;
+      if (stats.size > maxFileSize) {
+        scanWarnings.push(`Skipping large spec file (${(stats.size / 1024 / 1024).toFixed(2)} MB): ${specFile}`);
+        continue;
+      }
+      const content = await fs2.readFile(specFile, "utf-8");
+      const mappings = await mapSpecsToRules(specFile, content, rules);
+      for (const [ruleId, filePath] of mappings) {
+        if (!specFiles.has(ruleId)) {
+          specFiles.set(ruleId, []);
+        }
+        specFiles.get(ruleId).push(filePath);
+      }
+    }
+  }
+  const duration = Date.now() - startTime;
+  return {
+    rules,
+    constraints,
+    testFiles,
+    specFiles,
+    warnings: scanWarnings,
+    filesScanned,
+    duration
+  };
+}
+async function extractRulesFromFile(filePath, content) {
+  const rules = [];
+  const defineRulePattern = /defineRule\s*\(\s*\{([^}]+)\}\s*\)/g;
+  let match;
+  while ((match = defineRulePattern.exec(content)) !== null) {
+    const ruleConfig = match[1];
+    const idMatch = /id:\s*['"]([^'"]+)['"]/.exec(ruleConfig);
+    const descMatch = /description:\s*['"]([^'"]+)['"]/.exec(ruleConfig);
+    if (idMatch) {
+      const id = idMatch[1];
+      const description = descMatch ? descMatch[1] : "";
+      rules.push({
+        id,
+        description,
+        impl: () => [],
+        // Placeholder
+        meta: {
+          sourceFile: filePath,
+          discovered: true
+        }
+      });
+    }
+  }
+  return rules;
+}
+async function extractConstraintsFromFile(filePath, content) {
+  const constraints = [];
+  const defineConstraintPattern = /defineConstraint\s*\(\s*\{([^}]+)\}\s*\)/g;
+  let match;
+  while ((match = defineConstraintPattern.exec(content)) !== null) {
+    const constraintConfig = match[1];
+    const idMatch = /id:\s*['"]([^'"]+)['"]/.exec(constraintConfig);
+    const descMatch = /description:\s*['"]([^'"]+)['"]/.exec(constraintConfig);
+    if (idMatch) {
+      const id = idMatch[1];
+      const description = descMatch ? descMatch[1] : "";
+      constraints.push({
+        id,
+        description,
+        impl: () => true,
+        // Placeholder
+        meta: {
+          sourceFile: filePath,
+          discovered: true
+        }
+      });
+    }
+  }
+  return constraints;
+}
+async function mapTestsToRules(testFile, content, rules) {
+  const mappings = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    if (content.includes(rule.id)) {
+      mappings.set(rule.id, testFile);
+    }
+  }
+  return mappings;
+}
+async function mapSpecsToRules(specFile, content, rules) {
+  const mappings = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    if (content.includes(rule.id)) {
+      mappings.set(rule.id, specFile);
+    }
+  }
+  return mappings;
+}
+async function findFiles(rootDir, options, warnings) {
+  const files = [];
+  async function walk(dir, depth) {
+    if (depth > options.maxDepth) {
+      return;
+    }
+    try {
+      const entries = await fs2.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path2.join(dir, entry.name);
+        const relativePath = path2.relative(rootDir, fullPath);
+        if (shouldExclude(relativePath, options.exclude)) {
+          continue;
+        }
+        if (entry.isDirectory()) {
+          await walk(fullPath, depth + 1);
+        } else if (entry.isFile()) {
+          if (shouldInclude(relativePath, options.include)) {
+            files.push(fullPath);
+          }
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && "code" in error) {
+        const nodeError = error;
+        if (nodeError.code === "EACCES" || nodeError.code === "EPERM") {
+          warnings.push(`Permission denied: ${dir}`);
+        } else {
+          warnings.push(`Error scanning ${dir}: ${error.message}`);
+        }
+      }
+    }
+  }
+  await walk(rootDir, 0);
+  return files;
+}
+function shouldExclude(relativePath, patterns) {
+  return patterns.some((pattern) => {
+    const regex = globToRegex(pattern);
+    return regex.test(relativePath);
+  });
+}
+function shouldInclude(relativePath, patterns) {
+  return patterns.some((pattern) => {
+    const regex = globToRegex(pattern);
+    return regex.test(relativePath);
+  });
+}
+function globToRegex(pattern) {
+  let regexPattern = pattern.replace(/\\/g, "\\\\").replace(/\./g, "\\.").replace(/\*\*/g, "___DOUBLESTAR___").replace(/\*/g, "[^/]*").replace(/___DOUBLESTAR___/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${regexPattern}$`);
+}
+async function inferContractFromFile(filePath, ruleId) {
+  const content = await fs2.readFile(filePath, "utf-8");
+  const behavior = inferBehavior(content, ruleId);
+  const invariants = inferInvariants(content);
+  return {
+    ruleId,
+    behavior,
+    invariants,
+    examples: []
+    // Populated separately from tests
+  };
+}
+function inferBehavior(content, ruleId) {
+  const jsdocMatch = /\/\*\*\s*\n\s*\*\s*([^\n]+)/.exec(content);
+  if (jsdocMatch) {
+    return jsdocMatch[1].trim();
+  }
+  const descMatch = /description:\s*['"]([^'"]+)['"]/.exec(content);
+  if (descMatch) {
+    return descMatch[1];
+  }
+  return `Process ${ruleId} events`;
+}
+function inferInvariants(content) {
+  const invariants = [];
+  const assertPattern = /assert\s*\([^)]+,\s*['"]([^'"]+)['"]\)/g;
+  let match;
+  while ((match = assertPattern.exec(content)) !== null) {
+    invariants.push(match[1]);
+  }
+  return invariants;
+}
+
+// src/decision-ledger/reverse-generator.ts
+async function generateContractFromRule(descriptor, options = {}) {
+  const {
+    aiProvider = "none",
+    confidenceThreshold = 0.7,
+    includeAssumptions = true,
+    generateExamples = true,
+    sourceFile,
+    testFiles = [],
+    specFiles = []
+  } = options;
+  const warnings = [];
+  if (aiProvider !== "none") {
+    try {
+      const aiResult = await generateWithAI(descriptor, options);
+      if (aiResult.confidence >= confidenceThreshold) {
+        return aiResult;
+      }
+      warnings.push(
+        `AI confidence ${aiResult.confidence} below threshold ${confidenceThreshold}, falling back to heuristic`
+      );
+    } catch (error) {
+      warnings.push(`AI generation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const heuristicResult = await generateWithHeuristics(
+    descriptor,
+    { sourceFile, testFiles, specFiles, includeAssumptions, generateExamples }
+  );
+  return {
+    ...heuristicResult,
+    warnings: [...warnings, ...heuristicResult.warnings]
+  };
+}
+async function generateWithAI(descriptor, options) {
+  const { aiProvider, openaiApiKey, githubToken } = options;
+  if (aiProvider === "openai") {
+    if (!openaiApiKey) {
+      throw new Error("OpenAI API key is required for OpenAI provider");
+    }
+    return await generateWithOpenAI(descriptor, openaiApiKey, options);
+  }
+  if (aiProvider === "github-copilot") {
+    if (!githubToken) {
+      throw new Error("GitHub token is required for GitHub Copilot provider");
+    }
+    return await generateWithGitHubCopilot(descriptor, githubToken, options);
+  }
+  if (aiProvider === "auto") {
+    if (githubToken) {
+      return await generateWithGitHubCopilot(descriptor, githubToken, options);
+    }
+    if (openaiApiKey) {
+      return await generateWithOpenAI(descriptor, openaiApiKey, options);
+    }
+    throw new Error("Auto AI provider requires either GitHub token or OpenAI API key");
+  }
+  throw new Error(`Unsupported AI provider: ${aiProvider}`);
+}
+async function generateWithOpenAI(descriptor, _apiKey, options) {
+  return await generateWithHeuristics(descriptor, {
+    sourceFile: options.sourceFile,
+    testFiles: options.testFiles,
+    specFiles: options.specFiles,
+    includeAssumptions: options.includeAssumptions,
+    generateExamples: options.generateExamples
+  });
+}
+async function generateWithGitHubCopilot(descriptor, _token, options) {
+  return await generateWithHeuristics(descriptor, {
+    sourceFile: options.sourceFile,
+    testFiles: options.testFiles,
+    specFiles: options.specFiles,
+    includeAssumptions: options.includeAssumptions,
+    generateExamples: options.generateExamples
+  });
+}
+async function generateWithHeuristics(descriptor, options) {
+  const warnings = [];
+  const { sourceFile, testFiles = [], specFiles = [] } = options;
+  let behavior = descriptor.description || `Process ${descriptor.id}`;
+  let examples = [];
+  let invariants = [];
+  let assumptions = [];
+  let references = [];
+  if (sourceFile) {
+    try {
+      const inferred = await inferContractFromFile(sourceFile, descriptor.id);
+      if (inferred.behavior) {
+        behavior = inferred.behavior;
+      }
+      if (inferred.invariants && inferred.invariants.length > 0) {
+        invariants = inferred.invariants;
+      }
+    } catch (error) {
+      warnings.push(`Failed to analyze source file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (options.generateExamples && testFiles.length > 0) {
+    for (const testFile of testFiles) {
+      try {
+        const testExamples = await extractExamplesFromTests(testFile, descriptor.id);
+        examples.push(...testExamples);
+      } catch (error) {
+        warnings.push(`Failed to extract examples from ${testFile}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  if (examples.length === 0) {
+    examples.push({
+      given: `System is in a valid state`,
+      when: `${descriptor.id} is triggered`,
+      then: `Expected outcome is produced`
+    });
+    if (!options.generateExamples) {
+      warnings.push("Example generation disabled - using default example");
+    } else if (!testFiles || testFiles.length === 0) {
+      warnings.push("No test files provided - using default example");
+    } else {
+      warnings.push("No examples could be extracted from provided test files - using default example");
+    }
+  }
+  if (specFiles.length > 0) {
+    references = specFiles.map((file) => ({
+      type: "spec",
+      url: file,
+      description: `Specification for ${descriptor.id}`
+    }));
+  }
+  if (options.includeAssumptions) {
+    assumptions = generateDefaultAssumptions(descriptor);
+  }
+  const contract = defineContract({
+    ruleId: descriptor.id,
+    behavior,
+    examples,
+    invariants: invariants.length > 0 ? invariants : [`${descriptor.id} maintains system invariants`],
+    assumptions,
+    references
+  });
+  let confidence = 0.5;
+  const bonuses = [];
+  if (sourceFile) bonuses.push(0.1);
+  if (testFiles.length > 0) bonuses.push(0.2);
+  if (specFiles.length > 0) bonuses.push(0.1);
+  if (examples.length > 1) bonuses.push(0.1);
+  const totalBonus = Math.min(bonuses.reduce((sum, b) => sum + b, 0), 0.4);
+  confidence = confidence + totalBonus;
+  return {
+    contract,
+    confidence,
+    method: "heuristic",
+    warnings
+  };
+}
+async function extractExamplesFromTests(testFile, _ruleId) {
+  const fs3 = await import("fs/promises");
+  const content = await fs3.readFile(testFile, "utf-8");
+  const examples = [];
+  const testPattern = /(?:it|test)\s*\(\s*(?:'((?:\\'|[^'])*)'|"((?:\\"|[^"])*)"|`((?:\\`|[^`])*?)`)/g;
+  let match;
+  while ((match = testPattern.exec(content)) !== null) {
+    const description = match[1] ?? match[2] ?? match[3] ?? "";
+    if (description.includes("when") || description.includes("should")) {
+      examples.push(parseTestDescription(description));
+    }
+  }
+  return examples;
+}
+function parseTestDescription(description) {
+  const parts = description.split(/\b(?:when|should)\b/i);
+  if (parts.length >= 2) {
+    return {
+      given: parts[0].trim() || "Initial state",
+      when: parts.length > 2 ? parts[1].trim() : "Action is triggered",
+      then: parts[parts.length - 1].trim() || "Expected outcome occurs"
+    };
+  }
+  return {
+    given: description,
+    when: "Action is triggered",
+    then: "Expected outcome occurs"
+  };
+}
+function generateDefaultAssumptions(descriptor) {
+  return [
+    {
+      id: `${descriptor.id}-assumption-1`,
+      statement: "Input data is valid and well-formed",
+      confidence: 0.8,
+      justification: "Standard assumption for rule processing",
+      impacts: ["tests", "code"],
+      status: "active"
+    },
+    {
+      id: `${descriptor.id}-assumption-2`,
+      statement: "System state is consistent before rule execution",
+      confidence: 0.7,
+      justification: "Required for deterministic rule behavior",
+      impacts: ["spec", "tests"],
+      status: "active"
+    }
+  ];
+}
+
+export {
+  isContract,
+  defineContract,
+  getContract,
+  getContractFromDescriptor,
+  writeLogicLedgerEntry,
+  scanRepository,
+  generateContractFromRule
+};