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 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 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 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},//...]}]}]