Configuration

The unentropy.json file configures which metrics to track, storage options, and quality gate thresholds. This reference covers all configuration options.

File Location

Place unentropy.json in your project root directory:

my-project/
├── unentropy.json
├── package.json
└── src/

Basic Structure

{
  "metrics": {
    "metric-id": {
      "type": "numeric",
      "command": "echo 42"
    }
  },
  "storage": {
    "type": "sqlite-artifact"
  },
  "qualityGate": {
    "mode": "soft",
    "thresholds": []
  }
}

Metrics

The metrics object defines which metrics to track. Each key is a unique metric identifier.

Metric Configuration

{
  "metrics": {
    "coverage": {
      "$ref": "coverage",
      "name": "Test Coverage",
      "description": "Percentage of code covered by tests",
      "command": "@collect coverage-lcov ./coverage/lcov.info",
      "unit": "percent"
    }
  }
}

Fields

Metric ID (Object Key)

Type: string
Required: Yes
Pattern: ^[a-z0-9-]+$ (lowercase alphanumeric with hyphens)
Length: 1-64 characters

The object key serves as the unique metric identifier. Used in:

Database storage
Quality gate threshold references
Report displays

Examples: coverage, bundle-size, test-loc

`$ref`

Type: string
Required: No

Reference a built-in metric template. Inherits default properties like description, unit, and command.

{
  "loc": {
    "$ref": "loc"
  }
}

Available templates:

coverage - Test coverage percentage (supports --type line|branch|function)
loc - Lines of code
size - File/bundle size
build-time - Build duration
test-time - Test duration
dependencies-count - Dependency count

See Metrics Guide for details.

`name`

Type: string
Required: No
Max length: 256 characters

Display name for reports and charts. Defaults to the metric ID if omitted.

{
  "frontend-loc": {
    "$ref": "loc",
    "name": "Frontend Code Lines"
  }
}

`type`

Type: "numeric" or "label"
Required: Yes (unless using $ref)

Determines how values are stored and visualized:

numeric: Parsed as numbers, displayed as line charts
label: Stored as strings, displayed as bar charts

{
  "coverage": {
    "type": "numeric",
    "command": "@collect coverage-lcov ./coverage/lcov.info"
  },
  "status": {
    "type": "label",
    "command": "echo healthy"
  }
}

`description`

Type: string
Required: No
Max length: 256 characters

Human-readable explanation shown in reports.

{
  "bundle": {
    "$ref": "size",
    "description": "Production build size for main bundle"
  }
}

`command`

Type: string
Required: Yes
Max length: 1024 characters

Shell command to execute for collecting this metric. The command’s stdout is captured and parsed based on the metric type.

{
  "coverage": {
    "type": "numeric",
    "command": "@collect coverage-lcov ./coverage/lcov.info"
  },
  "api-count": {
    "type": "numeric",
    "command": "grep -r 'export function' src/api | wc -l"
  }
}

@collect shortcuts (faster, in-process execution):

@collect loc <path> - Count lines of code
@collect size <path> - Calculate file size
@collect coverage-lcov <path> [--type line|branch|function] - Extract LCOV coverage
@collect coverage-clover <paths...> [--type line|branch|function] - Extract and merge Clover XML coverage
@collect coverage-cobertura <paths...> [--type line|branch|function] - Extract and merge Cobertura XML coverage

`unit`

Type: string
Required: No
Max length: 10 characters

Display unit for numeric metrics. Used for formatting in reports.

Valid units:

percent - Displays as 87.5%
integer - Displays as 1,234
bytes - Displays as 1.5 MB (auto-scales)
duration - Displays as 1m 30s (auto-scales)
decimal - Displays as 3.14

{
  "coverage": {
    "type": "numeric",
    "command": "@collect coverage-lcov ./coverage/lcov.info",
    "unit": "percent"
  }
}

Metric Limits

Minimum metrics: 1
Maximum metrics: 50
Metric ID length: 1-64 characters
Command timeout: 30 seconds (configurable per-metric)

Command Execution

Commands run with these environment variables:

Variable	Description	Example
`UNENTROPY_COMMIT_SHA`	Current git commit	`a3f5c2b...`
`UNENTROPY_BRANCH`	Current git branch	`main`
`UNENTROPY_RUN_ID`	GitHub Actions run ID	`1234567890`
`UNENTROPY_RUN_NUMBER`	GitHub Actions run number	`42`
`UNENTROPY_ACTOR`	User who triggered run	`dependabot[bot]`
`UNENTROPY_METRIC_KEY`	Current metric ID	`coverage`
`UNENTROPY_METRIC_TYPE`	Current metric type	`numeric`

Execution rules:

Runs in repository root directory
Uses /bin/sh shell environment
Stdout is captured and parsed
Stderr is logged (doesn’t fail metric)
Exit code ignored (only output matters)

Storage

Configure where metrics data is stored.

Artifact Storage (Default)

{
  "storage": {
    "type": "sqlite-artifact"
  }
}

Or omit the storage block entirely—artifact storage is the default.

Options:

{
  "storage": {
    "type": "sqlite-artifact",
    "artifactName": "unentropy-metrics",
    "branch": "main"
  }
}

artifactName: Artifact name (default: unentropy-metrics)
branch: Branch to search (default: current branch)

S3 Storage

{
  "storage": {
    "type": "sqlite-s3"
  }
}

S3 credentials are provided as GitHub Action inputs, not in the config file:

- uses: unentropy/track-metrics-action@v1
  with:
    s3-endpoint: ${{ secrets.S3_ENDPOINT }}
    s3-access-key-id: ${{ secrets.S3_ACCESS_KEY_ID }}
    s3-secret-access-key: ${{ secrets.S3_SECRET_ACCESS_KEY }}
    s3-bucket: my-metrics-bucket
    s3-region: us-east-1

See Storage Guide for setup details.

Local Storage

{
  "storage": {
    "type": "sqlite-local"
  }
}

Database stored at ./unentropy.db in your project directory. Use for local development only (doesn’t persist in CI).

Quality Gate

Configure thresholds to enforce on pull requests.

Basic Quality Gate

{
  "qualityGate": {
    "mode": "soft",
    "thresholds": [
      {
        "metric": "coverage",
        "mode": "min",
        "target": 80
      }
    ]
  }
}

Quality Gate Mode

Controls how threshold violations are handled:

{
  "qualityGate": {
    "mode": "soft"
  }
}

Modes:

off - Disabled (no evaluation)
soft - Evaluates and posts comments, never fails build (default)
hard - Fails build when thresholds violated

Thresholds

Array of threshold rules for metrics:

{
  "qualityGate": {
    "thresholds": [
      {
        "metric": "coverage",
        "mode": "min",
        "target": 80
      },
      {
        "metric": "bundle",
        "mode": "max",
        "target": 500000
      },
      {
        "metric": "loc",
        "mode": "no-regression"
      }
    ]
  }
}

Threshold Fields

`metric`

Type: string
Required: Yes

Metric ID to evaluate. Must match a metric key in the metrics object.

`mode`

Type: string
Required: Yes

Comparison mode:

min - Metric must not drop below target
max - Metric must not exceed target
no-regression - Metric must not decrease from baseline
delta-max-drop - Metric can increase, but not more than maxDropPercent percentage

`target`

Type: number
Required: Yes (for min and max modes)

Threshold value. Meaning depends on mode:

min / max: Absolute value

Not used for no-regression or delta-max-drop modes.

`maxDropPercent`

Type: number
Required: Yes (only for delta-max-drop mode)

Maximum allowed percentage increase (e.g., 5 = 5% max increase).

{
  "metric": "bundle",
  "mode": "delta-max-drop",
  "maxDropPercent": 5
}

See Quality Gates Guide for examples.

Report

Configure the appearance and layout of generated HTML reports.

Report Theming

Control the visual appearance of your reports with built-in themes or custom palettes.

`report.theme`

Type: string | object
Default: "lattice"

Select a built-in palette or provide custom color overrides.

Built-in palettes:

Value	Description
`"lattice"`	Cool blue accent (default)
`"flux"`	Warm amber accent
`"halftone"`	Purple accent
`"specimen"`	Green accent

Custom palette (object with dark and/or light keys):

{
  "report": {
    "theme": {
      "dark": { "--accent": "#ff00ff" },
      "light": { "--accent": "#aa00aa" }
    }
  }
}

Available CSS variables for custom palettes:

Variable	Used for
`--bg`	Page background
`--surface`	Card backgrounds
`--surface-card`	Elevated card surfaces
`--border`	Default borders
`--border-soft`	Subtle dividers
`--text`	Primary text
`--text-dim`	Secondary text
`--text-muted`	Placeholder/disabled text
`--accent`	Highlights and links
`--up`	Positive trend indicators
`--down`	Negative trend indicators
`--warn`	Warning states

Each value must be a 7-character hex color (e.g., #1c2230). Omitted variables fall back to Lattice defaults.

`report.mode`

Type: "auto" | "light" | "dark"
Default: "auto"

Control how the report selects between light and dark palettes.

Value	Behavior
`"auto"`	Emits both palettes; `prefers-color-scheme` selects at runtime
`"light"`	Locks to light palette; emits only light CSS variables
`"dark"`	Locks to dark palette; emits only dark CSS variables

{
  "report": {
    "theme": "flux",
    "mode": "dark"
  }
}

Report Layout

Organize metrics into named sections and combine related metrics on a single chart.

`report.sections`

Type: SectionConfig[]
Required: No

Define named, visually separated groups of charts. When absent, the report uses a flat layout with all metrics displayed in definition order.

Each section contains:

{
  "report": {
    "sections": [
      {
        "name": "Code Size",
        "description": "Source code metrics by language",
        "charts": [
          { "metrics": "typescript-loc" },
          { "metrics": "javascript-loc" }
        ]
      }
    ]
  }
}

Section Fields

Field	Type	Required	Description
`name`	string	Yes	Section header text (max 256 characters)
`description`	string	No	Subtitle shown below the header
`charts`	`ChartConfig[]`	Yes	Charts to render, in display order

Chart Configuration

Field	Type	Required	Description
`metrics`	`string \| string[]`	Yes	Metric ID(s) to plot. Array plots multiple metrics on one chart.
`title`	string	No	Custom chart title. Defaults to metric name(s) when omitted.

Single-metric chart:

{ "metrics": "bundle-size", "title": "Production Bundle Size" }

Multi-metric chart:

{ "metrics": ["modern-classes", "legacy-classes"], "title": "Modern vs Legacy" }

Metrics with different units or scales automatically receive dual Y-axes. A legend identifies each series and can be clicked to toggle visibility.

Report Validation

Unknown theme string → warning logged, falls back to "lattice"
Custom theme with partial variables → missing variables filled from Lattice defaults
Invalid mode value → validation error at config load time
Invalid hex format in custom theme → validation error at config load time
Empty sections array → validation error (remove the block or define at least one section)
Unknown metrics references in charts → silently omitted from the report
Metrics not referenced in any chart → omitted from the report with no warning

Complete Example

{
  "metrics": {
    "coverage": {
      "$ref": "coverage",
      "name": "Test Coverage",
      "description": "Overall test coverage percentage",
      "command": "@collect coverage-lcov ./coverage/lcov.info"
    },
    "src-loc": {
      "$ref": "loc",
      "name": "Source Code Lines",
      "command": "@collect loc ./src --language TypeScript"
    },
    "test-loc": {
      "$ref": "loc",
      "name": "Test Code Lines",
      "command": "@collect loc ./tests"
    },
    "bundle": {
      "$ref": "size",
      "name": "Production Bundle",
      "command": "@collect size ./dist/**/*.js"
    },
    "api-endpoints": {
      "type": "numeric",
      "name": "API Endpoints",
      "description": "Number of exported API functions",
      "command": "grep -r 'export.*function' src/api | wc -l",
      "unit": "integer"
    }
  },
  "storage": {
    "type": "sqlite-artifact"
  },
  "qualityGate": {
    "mode": "soft",
    "thresholds": [
      {
        "metric": "coverage",
        "mode": "min",
        "target": 80
      },
      {
        "metric": "bundle",
        "mode": "delta-max-drop",
        "maxDropPercent": 5
      },
      {
        "metric": "src-loc",
        "mode": "no-regression"
      }
    ]
  },
  "report": {
    "theme": "specimen",
    "mode": "auto",
    "sections": [
      {
        "name": "Code Size",
        "description": "Source code and build artifact metrics",
        "charts": [
          { "metrics": ["src-loc", "test-loc"], "title": "Lines of Code" },
          { "metrics": "bundle", "title": "Production Bundle Size" }
        ]
      },
      {
        "name": "Quality",
        "charts": [
          { "metrics": "coverage" },
          { "metrics": "api-endpoints" }
        ]
      }
    ]
  }
}

Validation

Validate your configuration locally:

bunx unentropy verify

Common validation errors:

Invalid Metric ID

Error: Invalid metric key "Test-Coverage"
Keys must be lowercase with hyphens only (pattern: ^[a-z0-9-]+$)
Example: test-coverage

Invalid Metric Type

Error in metric "coverage": type must be either 'numeric' or 'label'
Found: 'percentage'

Empty Command

Error in metric "test-coverage": command cannot be empty
Provide a shell command that outputs the metric value

Missing Required Fields

Error in metric "test-coverage": missing required fields
Required: type, command
Found: type

Empty Report Sections

Error: report.sections cannot be empty
Remove the report block or define at least one section

Empty Section Charts

Error: Section "Code Size" has no charts
Each section must contain at least one chart

Invalid Report Mode

Error: mode must be one of: auto, light, dark
Found: "system"

Invalid Theme Value

Error: theme values must be 7-character hex (e.g. #1c2230)
Found: "#ff00f" at report.theme.dark.--accent

Metrics Guide - Metric configuration examples
Quality Gates Guide - Threshold setup
Storage Guide - Storage configuration
CLI Reference - Validation commands