@jstn-sdk/ma 0.1.13 → 0.14.0

package/src/quality/ai-quality-orchestrator.js

@@ -0,0 +1,328 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeJson } from "../fs-utils.js";
+import { packageRoot } from "../paths.js";
+
+const QUALITY_ROOT = path.join(".ma", "quality");
+let appendQueue = Promise.resolve();
+
+function violation(rule, severity, message, context, fix) {
+  return {
+    rule,
+    severity,
+    message,
+    ...(context?.filePath ? { location: { file: context.filePath, line: 1, column: 1 } } : {}),
+    ...(fix ? { fix } : {}),
+  };
+}
+
+function staticViolations(code, context) {
+  const findings = [];
+  if (/\bfetch\s*\(/.test(code) && !/AbortController|\btimeout\b|setTimeout/.test(code))
+    findings.push(
+      violation(
+        "network-calls-must-have-timeouts",
+        "critical",
+        "Network calls must use an abort or timeout boundary.",
+        context,
+        "Use AbortController with a bounded timeout.",
+      ),
+    );
+  if (/\b(?:eval|Function)\s*\(/.test(code))
+    findings.push(
+      violation(
+        "no-dynamic-code-execution",
+        "critical",
+        "Dynamic code execution is forbidden.",
+        context,
+      ),
+    );
+  if (/:\s*any\b/.test(code))
+    findings.push(
+      violation(
+        "no-any-types",
+        "error",
+        "TypeScript any is forbidden in generated code.",
+        context,
+        "Use a specific type or unknown with a type guard.",
+      ),
+    );
+  if (/\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9_]{16,}|AIza[0-9A-Za-z-_]{20,})\b/.test(code))
+    findings.push(
+      violation(
+        "no-hardcoded-secrets",
+        "critical",
+        "A credential-shaped value was found in generated code.",
+        context,
+      ),
+    );
+  if (
+    (context?.filePath?.includes("/controllers/") || context?.filePath?.includes("/routes/")) &&
+    /db\.collection|sequelize\.query|prisma\.\w+/.test(code)
+  )
+    findings.push(
+      violation(
+        "no-direct-db-access-from-controllers",
+        "error",
+        "Controllers must use a service boundary for database access.",
+        context,
+      ),
+    );
+  return findings;
+}
+
+function calculateQualityScore(kpis) {
+  const deletion = Math.min(
+    (Math.max(0, kpis.linesDeleted) / Math.max(kpis.linesAdded, 1)) * 30,
+    30,
+  );
+  const stability = 30 / (1 + Math.abs(kpis.p95LatencyDelta) / 100);
+  const security =
+    kpis.securityIssuesFound === 0
+      ? 20
+      : Math.min(kpis.securityIssuesFixed / kpis.securityIssuesFound, 1) * 20;
+  const coverage = Math.max(0, Math.min(kpis.testCoverage, 1)) * 20;
+  const cost = kpis.cloudCostDelta <= 0 ? 10 : Math.max(0, 10 - kpis.cloudCostDelta * 10);
+  return (
+    Math.round(
+      Math.max(0, Math.min(100, deletion + stability + security + coverage + cost)) * 100,
+    ) / 100
+  );
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`${command} timed out`));
+    }, options.timeoutMs ?? 30_000);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? 1, stdout: stdout.toString(), stderr: stderr.toString() });
+    });
+  });
+}
+
+export class AIQualityOrchestrator {
+  constructor(config = {}) {
+    this.config = { projectRoot: process.cwd(), requireTests: true, ...config };
+  }
+
+  async validate(code, context = {}) {
+    if (typeof code !== "string" || !code.trim())
+      throw new Error("Quality validation requires generated code");
+    const violations = staticViolations(code, context);
+    const semgrep = await this.runSemgrep(code, context);
+    violations.push(...semgrep.violations);
+    const architecture = await this.runArchUnit(code, context);
+    violations.push(...(architecture.violations ?? []));
+    if (this.config.requireTests && !context.testEvidence?.approved)
+      violations.push(
+        violation(
+          "tests-before-code",
+          "critical",
+          "Generated code has no approved test evidence.",
+          context,
+          "Provide approved tests before accepting generated code.",
+        ),
+      );
+    const kpis = {
+      linesDeleted: 0,
+      linesAdded: code.split("\n").length,
+      cloudCostDelta: 0,
+      p95LatencyDelta: 0,
+      testCoverage: Number(context.testCoverage ?? 0),
+      securityIssuesFound: violations.filter((v) => v.severity === "critical").length,
+      securityIssuesFixed: 0,
+      qualityScore: 0,
+    };
+    kpis.qualityScore = calculateQualityScore(kpis);
+    const blocked =
+      violations.some((item) => item.severity === "critical" || item.severity === "error") ||
+      kpis.qualityScore < (this.config.qualityScoreThreshold ?? 60);
+    const result = {
+      passed: !blocked,
+      score: kpis.qualityScore,
+      violations,
+      kpis,
+      reviewRequired: blocked,
+      ...(blocked ? { reviewReason: "One or more mandatory quality gates failed." } : {}),
+    };
+    await this.#append("violations.json", {
+      schemaVersion: "0.1.0",
+      record_type: "ai_quality_violations",
+      recordedAt: new Date().toISOString(),
+      violations,
+    });
+    await this.#append("kpis.json", {
+      schemaVersion: "0.1.0",
+      record_type: "ai_quality_kpis",
+      recordedAt: new Date().toISOString(),
+      kpis,
+    });
+    return result;
+  }
+
+  async runSemgrep(code, context = {}) {
+    if (typeof this.config.semgrepRunner === "function")
+      return this.config.semgrepRunner(code, context);
+    const root = context.projectRoot ?? this.config.projectRoot;
+    const projectRules = path.join(root, ".ma", "semgrep", "ai-quality-rules.yml");
+    let rules = context.rulesPath ?? projectRules;
+    if (!context.rulesPath) {
+      try {
+        await fs.access(projectRules);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          rules = path.join(packageRoot, "templates", "quality", "ai-quality-rules.yml");
+        } else {
+          return {
+            passed: false,
+            blocked: true,
+            available: false,
+            violations: [
+              violation(
+                "semgrep-rules-error",
+                "critical",
+                `Semgrep rules could not be read: ${error.message}`,
+                context,
+              ),
+            ],
+          };
+        }
+      }
+    }
+    const input = path.join(root, ".ma", "quality", `.scan-${randomUUID()}.ts`);
+    await fs.mkdir(path.dirname(input), { recursive: true });
+    await fs.writeFile(input, code, { mode: 0o600 });
+    try {
+      const result = await runCommand("semgrep", ["--config", rules, "--json", "--quiet", input], {
+        cwd: root,
+        timeoutMs: this.config.timeoutMs,
+      });
+      if (result.code === 0)
+        return { passed: true, blocked: false, available: true, violations: [] };
+      if (result.code === 1) {
+        const parsed = JSON.parse(result.stdout || "{}");
+        return {
+          passed: false,
+          blocked: true,
+          available: true,
+          violations: (parsed.results ?? []).map((item) =>
+            violation(
+              item.check_id,
+              "error",
+              item.extra?.message ?? "Semgrep rule failed",
+              context,
+              item.extra?.fix,
+            ),
+          ),
+        };
+      }
+      return {
+        passed: false,
+        blocked: true,
+        available: true,
+        violations: [
+          violation(
+            "semgrep-error",
+            "critical",
+            result.stderr.trim() || "Semgrep failed to execute",
+            context,
+          ),
+        ],
+      };
+    } catch (error) {
+      return {
+        passed: false,
+        blocked: true,
+        available: false,
+        violations: [
+          violation(
+            "semgrep-unavailable",
+            "critical",
+            `Semgrep is unavailable: ${error.message}`,
+            context,
+          ),
+        ],
+      };
+    } finally {
+      await fs.rm(input, { force: true });
+    }
+  }
+
+  async runArchUnit(code, context = {}) {
+    const violations = staticViolations(code, context).filter(
+      (item) => item.rule === "no-direct-db-access-from-controllers",
+    );
+    return { passed: violations.length === 0, blocked: violations.length > 0, violations };
+  }
+
+  async testDrivenGeneration(
+    requirement,
+    { generateTests, generateCode, approveTests, runTests } = {},
+  ) {
+    if (
+      ![generateTests, generateCode, approveTests, runTests].every((fn) => typeof fn === "function")
+    )
+      throw new Error(
+        "Test-driven generation requires explicit test, approval, code, and runner functions",
+      );
+    const tests = await generateTests(requirement);
+    if (!(await approveTests(tests))) throw new Error("Tests were not approved");
+    const code = await generateCode(requirement, tests);
+    const result = await runTests(tests, code);
+    if (!result?.allPassed || Number(result.coverage ?? 0) < 0.8)
+      throw new Error("Approved tests did not pass with 80% coverage");
+    return { tests, code };
+  }
+
+  async generateCursorRules(projectRoot) {
+    const content = `# AI Engineering Quality Standards\n\n## Enforced\n- Network calls require bounded AbortController timeouts.\n- Dynamic code execution and hardcoded credentials are forbidden.\n- User input must be validated and logs sanitized.\n- Database access belongs behind a service boundary.\n- Tests must be approved before generated production code.\n- Quality failures block acceptance.\n`;
+    await fs.mkdir(projectRoot, { recursive: true });
+    await fs.writeFile(path.join(projectRoot, ".cursorrules"), content, { mode: 0o644 });
+    return content;
+  }
+
+  async calculateQualityScore(kpis) {
+    return calculateQualityScore(kpis);
+  }
+
+  async #append(name, record) {
+    const file = path.join(this.config.projectRoot, QUALITY_ROOT, name);
+    const append = async () => {
+      let records = [];
+      try {
+        records = JSON.parse(await fs.readFile(file, "utf8"));
+      } catch {
+        /* first record */
+      }
+      if (!Array.isArray(records)) records = [];
+      records.push(record);
+      await writeJson(file, records.slice(-100));
+    };
+    appendQueue = appendQueue.then(append, append);
+    await appendQueue;
+  }
+}
+
+export { calculateQualityScore, staticViolations };

package/src/release-issue-gates.js

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+
 const ALLOWED_STATUSES = new Set(["pending", "in_progress", "blocked", "failed", "passed"]);
 const REQUIRED_PROOF_FIELDS = [
   "implementationEvidence",
@@ -5,6 +8,65 @@ const REQUIRED_PROOF_FIELDS = [
   "productionEvidence",
 ];
 
+function compareVersions(left, right) {
+  return right
+    .split(".")
+    .map(Number)
+    .reduce((result, value, index) => result || value - Number(left.split(".")[index]), 0);
+}
+
+export function resolveReleaseIssueGates(root, version = null) {
+  return resolveVersionedQaArtifact(root, "release-issue-gates", version);
+}
+
+export function resolveReleaseReadiness(root, version = null) {
+  return resolveVersionedQaArtifact(root, "release-readiness", version);
+}
+
+function resolveVersionedQaArtifact(root, prefix, version = null) {
+  const repoRoot = path.resolve(root);
+  let currentVersion = version;
+  if (!currentVersion) {
+    try {
+      currentVersion = JSON.parse(
+        fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"),
+      ).version;
+    } catch {
+      currentVersion = null;
+    }
+  }
+
+  const qaRoot = path.join(repoRoot, "docs", "qa");
+  const extension = prefix === "release-readiness" ? "md" : "json";
+  const currentPath = currentVersion
+    ? path.join(qaRoot, `${prefix}-${currentVersion}.${extension}`)
+    : null;
+  if (currentPath && fs.existsSync(currentPath)) {
+    return { path: currentPath, version: currentVersion, fallback: false };
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(qaRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const history = entries
+    .flatMap((entry) => {
+      const escapedPrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const match = entry.name.match(
+        new RegExp(`^${escapedPrefix}-(\\d+\\.\\d+\\.\\d+)\\.${extension}$`),
+      );
+      return entry.isFile() && match
+        ? [{ version: match[1], path: path.join(qaRoot, entry.name) }]
+        : [];
+    })
+    .sort((left, right) => compareVersions(left.version, right.version));
+  const previous = history[0];
+  return previous ? { ...previous, fallback: true } : null;
+}
+
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }

package/src/release-operations.js

@@ -0,0 +1,62 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const branchPattern = /^[A-Za-z0-9._/-]+$/;
+
+function assertBranch(value, label) {
+  if (typeof value !== "string" || !branchPattern.test(value) || value.includes("..")) {
+    throw new Error(`${label} is not a safe branch name`);
+  }
+}
+
+export function getGitOperation(sourceBranch, targetBranch) {
+  assertBranch(sourceBranch, "Source branch");
+  assertBranch(targetBranch, "Target branch");
+  return {
+    command: "git",
+    args: ["merge", "--no-ff", "--no-edit", "--", sourceBranch],
+    display: `git merge --no-ff --no-edit -- ${sourceBranch}`,
+    sourceBranch,
+    targetBranch,
+  };
+}
+
+export async function inspectGitOperation(root, sourceBranch, targetBranch) {
+  const operation = getGitOperation(sourceBranch, targetBranch);
+  try {
+    const [branch, status] = await Promise.all([
+      execFileAsync("git", ["branch", "--show-current"], { cwd: root, encoding: "utf8" }),
+      execFileAsync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf8" }),
+      execFileAsync("git", ["rev-parse", "--verify", `refs/heads/${sourceBranch}`], {
+        cwd: root,
+        encoding: "utf8",
+      }),
+    ]);
+    return {
+      ...operation,
+      available: true,
+      currentBranch: branch.stdout.trim(),
+      clean: status.stdout.trim() === "",
+      sourceExists: true,
+      blockers: status.stdout.trim() === "" ? [] : ["working tree is not clean"],
+    };
+  } catch (error) {
+    return {
+      ...operation,
+      available: false,
+      currentBranch: "",
+      clean: false,
+      sourceExists: false,
+      blockers: [error?.stderr?.trim() || "Git preflight failed"],
+    };
+  }
+}
+
+export async function executeGitOperation(root, operation) {
+  const result = await execFileAsync(operation.command, operation.args, {
+    cwd: root,
+    encoding: "utf8",
+  });
+  return { ...operation, stdout: result.stdout.trim(), stderr: result.stderr.trim() };
+}

package/src/runtime/agent-compat.js

@@ -0,0 +1,31 @@
+import { createRequire } from "node:module";
+import { Agents } from "@jstn-sdk/agents";
+
+const require = createRequire(import.meta.url);
+const agentCompatMetadata = require("@jstn-sdk/agents/package.json");
+
+export const agentCompatPackage = "@jstn-sdk/agents";
+export const agentCompatVersion = agentCompatMetadata.version;
+
+export function listAgentCompatAdapters() {
+  return Agents.list().map(({ id, vendor, product, surface, support, verification }) => ({
+    id,
+    vendor,
+    product,
+    surface,
+    support,
+    verification,
+  }));
+}
+
+export function detectAgentEnvironments(root) {
+  return Agents.detect(root);
+}
+
+export function compileAgentIntegrations(manifest, options = {}) {
+  return Agents.compile(manifest, options);
+}
+
+export function validateAgentIntegrations(root, options = {}) {
+  return Agents.validate(root, options);
+}