Task Result Schema

As mentioned, Checkup tasks gather data and return results in a specific schema format, and are composed together as part of the larger CLI schema.

Task results have their own sub-schema that they adhere to.

export interface TaskResult {
info: {
taskName: TaskName;
taskDisplayName: string;
category: string;
group?: string;
};
result: Record<string, any>;
}

The result property contains the raw result data that's gathered from the task. You can adapt these results to a number of different formats, depending on needs.

Summary results

Summary task results (tasks that have a category of metrics) are strictly informational in nature. They count a particular entity, such as a type, and display that value. Their main purpose is to help give a summary of the shape and size of a project, and to allow you to chart the changes to that shape and size over time.

The summary results have a simple integer value for the count property equivalent to the following:

export interface SummaryResult extends BaseResult {
type: 'summary';
count: number;
}

Summary example:

[
{
"info": {
"taskName": "demo",
"taskDisplayName": "Demo",
"category": "metrics",
},
"result": [
{
"key": "things we care about",
"count": 2,
"data": [
"path/to/first.js",
"path/to/second.js"
]
},
{
"key": "yet more important things",
"count": 2,
"data": [
"path/to/other.js",
"path/to/important.js"
]
}
]
}
]

Multi value results

Multi value results break down the data in specific ways. These are used to determine ways to sort the data in order to derive insights.

Multi value results contain a bit more information than summary results.

{
dataSummary: {
values: Record<string, number>;
dataKey: string;
total: number;
};
}
  • dataSummary.values - a dictionary of values used to subdivide and count specific pieces of data

  • dataSummary.dataKey - a string representing a property name that is the source of the aggregate data

  • dataSummary.total- the sum of data of the parent result

The dataSummary can be used to calculate percentages:

let completed = Object.values(dataSummary.values).reduce(
(total, value) => total + value,
0
);
‚Äč
let dataSummary = Math.round((completed / dataSummary.total) * 100);

The dataSummary contains a dataKey configuration value, which allows you to specify a key corresponding to the source of the values in the values dictionary. The dataKey is used to look up a property on the data, and the presence of unique values are used to count the total occurrences of that value.

Multi value example

In the example below, the ruleId dataKey is used to lookup the values referenced by the ruleId property in the data, and the occurrences of those unique values are summed and used as the value.

[
{
"info": {
"taskName": "eslint-summary",
"taskDisplayName": "Eslint Summary",
"category": "linting"
},
"result": [
{
"key": "eslint-errors",
"type": "multi-value",
"dataSummary": {
"values": {
"no-prototype-builtins": 20,
"no-redeclare": 3
},
"dataKey": "ruleId",
"total": 23
},
"data": [
{
"filePath": "/app/adapters/preference.js",
"ruleId": "no-prototype-builtins",
"message": "Do not access Object.prototype method 'hasOwnProperty' from target object.",
"severity": 2,
"line": 17,
"column": 31
},
{
"filePath": "/app/components/x-tracer.js",
"ruleId": "no-redeclare",
"message": "'window' is already defined as a built-in global variable.",
"severity": 2,
"line": 1,
"column": 25
},
//...
]
}
]
}
]

Lookup value results

Lookup value results are similar to multi value results, in that they summarize the data using a dataSummary property. Also similar to multi value results, they employ a dataKey to lookup the values of the properties in the data that the dataKey references.

In addition to the dataKey, they additionally have a valueKey. While the dataKey values ultimately form the keys in the values dictionary, the valueKey's values are summed to form the numeric value of those data keys.

Lookup value example

In the example below, the extension dataKey is used to lookup the values referenced by the extension property in the data. The lines valueKey is used to summarize the values.

[
{
"info": {
"taskName": "lines-of-code",
"taskDisplayName": "Lines of Code",
"category": "metrics"
},
"result": [
{
"key": "lines of code",
"type": "lookup-value",
"dataSummary": {
"values": {
"js": 44939,
"html": 201,
"scss": 14355,
"hbs": 10803,
"svg": 22836
},
"dataKey": "extension",
"valueKey": "lines",
"total": 93742
},
"data": [
{
"filePath": "/.eslintrc.js",
"extension": "js",
"lines": 359
},
{
"filePath": "/.template-lintrc.js",
"extension": "js",
"lines": 5
},
//...
]
}
]
}
]