Skip to content

PROGRAMMATIC.md

Latest commit

 

History

History
62 lines (48 loc) · 1.69 KB

PROGRAMMATIC.md

File metadata and controls

62 lines (48 loc) · 1.69 KB
Raw

Programmatic Use

Ubon is usable from Node, the CLI, and MCP. Agents should prefer MCP or JSON CLI output. Build scripts should prefer the Node API when they already have a file list or want to combine Ubon with another gate.

Node API

const { UbonScan } = require('ubon');

async function main() {
  const scanner = new UbonScan(false, true);
  const findings = await scanner.diagnose({
    directory: process.cwd(),
    fast: true,
    focusCritical: true,
    failOn: 'error',
    minConfidence: 0.8
  });

  if (findings.some((finding) => finding.type === 'error' && !finding.suppressed)) {
    process.exitCode = 1;
  }
}

main();

Stable CLI Contracts

Use these forms in automation:

ubon check --json --quiet
ubon check --ndjson --quiet
ubon check --preset agent
ubon changed --since origin/main --json --quiet
ubon verify --preset ci
ubon rules list --json

--json returns the v2 finding schema. --preset agent adds source context, explanations, and a small issue cap for repair loops. --ndjson emits one finding per line for streaming consumers. ubon rules list --json returns machine-readable rule metadata, sorted by rule id.

MCP Contracts

Use ubon.mcp when an assistant needs to inspect, explain, verify, or plan fixes without shelling out. Important tools:

  • ubon.check: fast static scan.
  • ubon.scan: full scan.
  • ubon.verify: pass/fail gate with failOn.
  • ubon.plan-fixes: ordered remediation plan.
  • ubon.rule-catalog: rule metadata.
  • ubon.status: project and harness status.

For diff-focused review, pass either changedFiles, gitChangedSince, or baseSha. baseSha is accepted as an alias for CI systems that already expose the merge base.