Skip to content

SCHEMA.md

Latest commit

 

History

History
227 lines (195 loc) · 7.81 KB

SCHEMA.md

File metadata and controls

227 lines (195 loc) · 7.81 KB

CodeView Report Schema

The report is a single JSON file at .codeview/report.json that the web app renders. This document describes the format. The Claude Code skill writes this file; the web app reads it.

Top-level Structure

{
  "version": 1,
  "generatedAt": "2026-04-04T12:00:00.000Z",
  "projectRoot": "/abs/path/to/project",
  "lastCommit": "abc123def456",
  "gitBranch": "main",
  "techStack": { ... },
  "overall": { ... },
  "tree": { ... },
  "issues": [ ... ]
}
Field Type Description
version number Schema version. Currently 1.
generatedAt string ISO-8601 timestamp when the report was written.
projectRoot string Absolute path to the project being analyzed.
lastCommit string? Git HEAD SHA when the scan ran. Used for incremental diffs. Omitted for non-git projects.
gitBranch string? Current git branch name. Omitted for non-git projects.
techStack object Detected languages, frameworks, tooling.
overall object Aggregate health summary.
tree object Hierarchical file tree with per-node status.
issues array Flat list of all findings.

techStack

{
  "primary": "TypeScript",
  "languages": {
    "TypeScript": 142,
    "JavaScript": 8,
    "CSS": 5,
    "Markdown": 15
  },
  "frameworks": ["React", "Node.js", "Express"],
  "packageManagers": ["pnpm"],
  "testFrameworks": ["vitest"],
  "buildTools": ["tsup", "vite"],
  "runtime": "node",
  "notes": "Monorepo with 3 packages under src/"
}
Field Type Description
primary string Dominant language by file count or LOC.
languages object File count per language.
frameworks string[] Detected frameworks (React, Django, Rails, etc.).
packageManagers string[] npm, pnpm, yarn, pip, poetry, cargo, etc.
testFrameworks string[] vitest, jest, pytest, go test, etc.
buildTools string[] tsup, vite, webpack, esbuild, etc.
runtime string? node, deno, bun, python, go, etc.
notes string? Freeform observations from Claude.

overall

{
  "status": "yellow",
  "score": 72,
  "totalFiles": 165,
  "analyzedFiles": 142,
  "skippedFiles": 23,
  "totalIssues": 47,
  "byDimension": {
    "silent-error-handling": 8,
    "type-safety-escapes": 12,
    "dead-code": 5
  },
  "bySeverity": {
    "critical": 2,
    "high": 8,
    "medium": 24,
    "low": 13
  }
}
Field Type Description
status "green" | "yellow" | "red" Overall health indicator (see Status Rules below).
score number 0-100 health score. Higher is better.
totalFiles number Total files discovered (respecting .gitignore).
analyzedFiles number Files actually analyzed (excluding binaries, vendor dirs, etc.).
skippedFiles number totalFiles - analyzedFiles.
totalIssues number Sum of all findings.
byDimension object Issue counts keyed by dimension ID.
bySeverity object Issue counts keyed by severity.

tree

A recursive tree node structure. Each node represents either a directory or file.

{
  "name": "root",
  "path": ".",
  "type": "directory",
  "status": "yellow",
  "issueCount": 47,
  "bySeverity": { "critical": 2, "high": 8, "medium": 24, "low": 13 },
  "children": [
    {
      "name": "src",
      "path": "src",
      "type": "directory",
      "status": "yellow",
      "issueCount": 40,
      "bySeverity": { "critical": 2, "high": 6, "medium": 22, "low": 10 },
      "children": [
        {
          "name": "auth.ts",
          "path": "src/auth.ts",
          "type": "file",
          "status": "red",
          "issueCount": 5,
          "bySeverity": { "critical": 2, "high": 1, "medium": 2, "low": 0 },
          "issueIds": ["i001", "i002", "i003", "i004", "i005"],
          "size": 342,
          "lines": 87
        }
      ]
    }
  ]
}
Field Type Description
name string Basename (e.g. auth.ts).
path string Relative path from projectRoot. Use . for root.
type "directory" | "file" Node type.
status "green" | "yellow" | "red" Rolled-up status for this node.
issueCount number Total issues in this node (including descendants for directories).
bySeverity object Severity breakdown for this node.
children array? Child nodes. Only present on directories.
issueIds string[]? Issue IDs attached to this node. Only present on files.
size number? File size in bytes (files only).
lines number? Line count (files only).

Status rolls up: a directory's status is the worst status of any descendant.

issues

Flat array of all findings. Each issue has a stable ID so the tree can reference it.

{
  "id": "i001",
  "file": "src/auth.ts",
  "line": 42,
  "endLine": 42,
  "dimension": "silent-error-handling",
  "category": "correctness",
  "severity": "high",
  "title": "Empty catch block swallows errors",
  "description": "The catch block at line 42 silently ignores errors thrown by fetchUser(). If the fetch fails, the function returns as if nothing happened, making the bug invisible.",
  "codeSnippet": "try {\n  const user = await fetchUser(id)\n  return user\n} catch {}",
  "suggestion": "Log the error with context and rethrow, or return a Result type that the caller can handle explicitly.",
  "references": ["https://github.com/goldbergyoni/nodebestpractices#-21-treat-errors"]
}
Field Type Description
id string Stable ID (i001, i002, ...). Used by tree nodes to reference issues.
file string Relative path to the file.
line number Starting line number (1-indexed).
endLine number? Ending line number for multi-line issues.
dimension string Dimension ID (e.g. silent-error-handling). See dimensions.md.
category "security" | "correctness" | "maintainability" | "quality" High-level grouping.
severity "critical" | "high" | "medium" | "low" Impact severity.
title string Short human-readable summary (one line).
description string Full explanation of the issue and why it matters.
codeSnippet string? Relevant code excerpt.
suggestion string? How to fix it.
references string[]? External docs, CVE IDs, best-practice links.

Status Rules

Status is determined solely by severity counts — not by the score value. A project with score 85 and a single high-severity issue is still red.

Apply in order, first match wins:

  1. critical > 0 OR high > 0 → red
  2. medium > 0 OR low > 0 → yellow
  3. Otherwise → green

Examples:

Critical High Medium Low Status
0 0 0 0 green
0 0 5 2 yellow
0 1 7 3 red (1 high)
0 4 11 6 red (4 high)
2 8 24 13 red (critical + high)

The same rule applies recursively to directory tree nodes.

Severity Guidelines

Severity Meaning Examples
critical Security vulnerability or broken production code Hardcoded secrets, SQL injection, auth bypass
high Will likely cause bugs or incidents Silent error handling, default-return masking, unhandled async
medium Code smell or technical debt Dead code, duplicate code, complexity hotspots
low Style or hygiene Commented-out code, TODO density, magic numbers

Score Formula

The overall.score is computed from severity counts:

score = max(0, 100 - (critical * 15) - (high * 5) - (medium * 2) - (low * 0.5))

Capped at 0, never negative. 100 = zero issues.