Output Format

The engine returns a structured AnalysisResult object. The CLI --format json flag serializes this directly.

TypeScript types

type AnalysisResult = {
  version: string;           // engine package version (e.g. "0.1.8")
  confidence: 'high' | 'medium' | 'low';
  score: number;             // 0–100
  hardFailures: RuleId[];    // e.g. ["C1", "O1"]
  pillars: Record<PillarName, PillarScore>;
  rules: Partial<Record<RuleId, RuleResult>>;
  tip?: string;              // actionable hint when manifest is missing
  confidenceCaveat?: string; // soft-critical warning at low confidence
  opportunities: {
    viewModelMigrations: ViewModelMigrationOpportunity[];
  };
  meta: {
    analyzedAt: string;      // ISO timestamp
    root: string;            // absolute path analyzed
    filesScanned: number;
    manifestFound: boolean;
    importGraphResolved: boolean;
  };
};

type PillarScore = {
  score: number;             // 0–100
  weight: number;            // 0.20
  rules: Partial<Record<RuleId, RuleResult>>;
};

type RuleResult = {
  id: RuleId;                // "C2"
  passed: boolean;
  severity: 'hard_failure' | 'warning' | 'recommendation';
  confidence: 'high' | 'medium' | 'low';
  scoreImpact: number;
  message: string;           // human-readable finding
  remediation?: string;      // fix guidance when rule fails
  locations?: Location[];    // files involved, if applicable
  inapplicable?: boolean;    // rule could not run on this stack (see below)
};

type Location = {
  path: string;              // relative to root
  line?: number;             // 1-based, optional
  endLine?: number;          // inclusive range end, optional
  detail?: string;
};

Confidence and applicability fields

confidence (top level) — how much to trust the score: high requires a manifest and a resolved import graph; medium means one of the two; low means neither. Reported per-rule as well, since individual analyzers have different signal strength.
confidenceCaveat — present when hard failures were detected at low confidence. The findings are real but may shift once a manifest is added; UIs should render them as soft-critical rather than blocking.
meta.importGraphResolved — false when the repo has no resolvable JS/TS sources (e.g. a Python or Go repo). Import-graph rules cannot run in that case.
inapplicable (per rule) — set on rules that could not be evaluated for this stack (B1, C3, C4, C5, C6 when the import graph is unresolved). Such rules carry passed: true and scoreImpact: 0 so they never move the score, and should be displayed as not evaluated, never as passing. See Scoring non-JS repositories.

Example output

{
  "version": "0.1",
  "confidence": "medium",
  "score": 72,
  "hardFailures": [],
  "pillars": {
    "discoverability": {
      "score": 85,
      "weight": 0.20,
      "rules": {
        "D1": { "id": "D1", "passed": true, "severity": "warning", "scoreImpact": 0, "message": "Root has 8 meaningful entries" },
        "D2": { "id": "D2", "passed": true, "severity": "warning", "scoreImpact": 0, "message": "All 3 workspaces have purpose statements" },
        "D3": { "id": "D3", "passed": true, "severity": "warning", "scoreImpact": 0, "message": "Source, test, and config directories are segregated" },
        "D4": { "id": "D4", "passed": false, "severity": "warning", "scoreImpact": 15, "message": "Utility dumping ground files found", "locations": [{ "path": "packages/shared/src/utils.ts" }] },
        "D5": { "id": "D5", "passed": true, "severity": "recommendation", "scoreImpact": 0, "message": "Max depth 4 before module boundary" },
        "D6": { "id": "D6", "passed": true, "severity": "warning", "scoreImpact": 0, "message": "No shadow or duplicate route handlers detected" }
      }
    },
    "context_efficiency": {
      "score": 60,
      "weight": 0.20,
      "rules": {
        "C1": { "id": "C1", "passed": true, "severity": "hard_failure", "scoreImpact": 0, "message": "No generated artifacts found in source tree" },
        "C2": { "id": "C2", "passed": false, "severity": "warning", "scoreImpact": 25, "message": "2 files exceed 400 lines", "locations": [
          { "path": "apps/api/src/routes/auth.ts", "detail": "847 lines" },
          { "path": "apps/web/src/pages/dashboard.tsx", "detail": "601 lines" }
        ]},
        "C3": { "id": "C3", "passed": true, "severity": "warning", "scoreImpact": 0, "message": "No file imports more than 15 distinct modules" },
        "C4": { "id": "C4", "passed": false, "severity": "recommendation", "scoreImpact": 0, "message": "1 files not in manifest.highFanIn: packages/ui/src/tokens.ts (23)", "locations": [
          { "path": "packages/ui/src/tokens.ts", "detail": "blast radius: 23 direct callers" }
        ]},
        "C5": { "id": "C5", "passed": true, "severity": "recommendation", "scoreImpact": 0, "message": "Max import depth 6" }
      }
    }
  },
  "meta": {
    "analyzedAt": "2026-04-30T14:23:00.000Z",
    "root": "/Users/dev/my-app",
    "filesScanned": 312,
    "manifestFound": false,
    "importGraphResolved": true
  }
}

Using the output

import { analyze } from '@clarxai/engine';

const result = await analyze({ root: process.cwd() });

// Gate on overall score
if (result.score < 70) {
  console.error(`Score ${result.score} is below threshold 70`);
  process.exit(1);
}

// Gate on hard failures
if (result.hardFailures.length > 0) {
  console.error(`Hard failures: ${result.hardFailures.join(', ')}`);
  process.exit(2);
}

// Find all failing warnings
const failingWarnings = Object.values(result.rules).filter(
  r => !r.passed && r.severity === 'warning'
);

Output Format

Output Format

TypeScript types

Confidence and applicability fields

Example output

Using the output

On this page