Skip to content

Commit 63bf44c

Browse files
matejchalkmatejchalk
committed
feat(models): define tree data structure for audit details
1 parent 9cd4a7f commit 63bf44c

File tree

9 files changed

+293
-43
lines changed

9 files changed

+293
-43
lines changed

‎package-lock.json

Lines changed: 5 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@
118118
"verdaccio": "^5.32.2",
119119
"vite": "^5.4.8",
120120
"vitest": "1.3.1",
121-
"zod2md": "^0.1.3"
121+
"zod2md": "^0.1.7"
122122
},
123123
"optionalDependencies": {
124124
"@esbuild/darwin-arm64": "^0.19.12",

‎packages/models/docs/models-reference.md

Lines changed: 109 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,11 @@ Detailed information
66

77
_Object containing the following properties:_
88

9-
| Property | Description | Type |
10-
| :------- | :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11-
| `issues` | List of findings | _Array of [Issue](#issue) items_ |
12-
| `table` | Table of related findings | _Object with properties:_<ul><li>`title`: `string` - Display title for table</li><li>`columns`: _Array of [TableAlignment](#tablealignment) items_</li><li>`rows`: _Array of [TableRowPrimitive](#tablerowprimitive) items_</li></ul> _or_ _Object with properties:_<ul><li>`title`: `string` - Display title for table</li><li>`columns`: _Array of [TableAlignment](#tablealignment) items_ _or_ _Array of [TableColumnObject](#tablecolumnobject) items_</li><li>`rows`: _Array of [TableRowObject](#tablerowobject) items_</li></ul> |
9+
| Property | Description | Type |
10+
| :------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11+
| `issues` | List of findings | _Array of [Issue](#issue) items_ |
12+
| `table` | Table of related findings | _Object with properties:_<ul><li>`title`: `string` - Display title for table</li><li>`columns`: _Array of [TableAlignment](#tablealignment) items_</li><li>`rows`: _Array of [TableRowPrimitive](#tablerowprimitive) items_</li></ul> _or_ _Object with properties:_<ul><li>`title`: `string` - Display title for table</li><li>`columns`: _Array of [TableAlignment](#tablealignment) items_ _or_ _Array of [TableColumnObject](#tablecolumnobject) items_</li><li>`rows`: _Array of [TableRowObject](#tablerowobject) items_</li></ul> |
13+
| `trees` | Findings in tree structure | _Array of [Tree](#tree) items_ |
1314

1415
_All properties are optional._
1516

@@ -97,6 +98,32 @@ _Object containing the following properties:_
9798

9899
_(\*) Required._
99100

101+
## BasicTreeNode
102+
103+
_Object containing the following properties:_
104+
105+
| Property | Description | Type |
106+
| :-------------- | :--------------------------------------------- | :----------------------------------------------- |
107+
| **`name`** (\*) | Text label for node | `string` (_min length: 1_) |
108+
| `values` | Additional values for node | `Record<string, number \| string>` |
109+
| `children` | Direct descendants of this node (omit if leaf) | _Array of [BasicTreeNode](#basictreenode) items_ |
110+
111+
_(\*) Required._
112+
113+
## BasicTree
114+
115+
Generic tree
116+
117+
_Object containing the following properties:_
118+
119+
| Property | Description | Type |
120+
| :-------------- | :----------- | :------------------------------ |
121+
| `title` | Heading | `string` |
122+
| `type` | Discriminant | `'basic'` |
123+
| **`root`** (\*) | Root node | [BasicTreeNode](#basictreenode) |
124+
125+
_(\*) Required._
126+
100127
## CategoryConfig
101128

102129
_Object containing the following properties:_
@@ -180,6 +207,57 @@ _Object containing the following properties:_
180207

181208
_(\*) Required._
182209

210+
## CoverageTreeMissingLOC
211+
212+
Uncovered line of code, optionally referring to a named function/class/etc.
213+
214+
_Object containing the following properties:_
215+
216+
| Property | Description | Type |
217+
| :------------------- | :-------------------------------- | :------------------- |
218+
| **`startLine`** (\*) | Start line | `number` (_int, >0_) |
219+
| `startColumn` | Start column | `number` (_int, >0_) |
220+
| `endLine` | End line | `number` (_int, >0_) |
221+
| `endColumn` | End column | `number` (_int, >0_) |
222+
| `name` | Identifier of function/class/etc. | `string` |
223+
| `kind` | E.g. "function", "class" | `string` |
224+
225+
_(\*) Required._
226+
227+
## CoverageTreeNode
228+
229+
_Object containing the following properties:_
230+
231+
| Property | Description | Type |
232+
| :---------------- | :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
233+
| **`name`** (\*) | File or folder name | `string` (_min length: 1_) |
234+
| **`values`** (\*) | Coverage metrics for file/folder | _Object with properties:_<ul><li>`coverage`: `number` (_≥0, ≤1_) - Coverage ratio</li><li>`missing`: _Array of [CoverageTreeMissingLOC](#coveragetreemissingloc) items_ - Uncovered lines of code</li></ul> |
235+
| `children` | Files and folders contained in this folder (omit if file) | _Array of [CoverageTreeNode](#coveragetreenode) items_ |
236+
237+
_(\*) Required._
238+
239+
## CoverageTree
240+
241+
Coverage for files and folders
242+
243+
_Object containing the following properties:_
244+
245+
| Property | Description | Type |
246+
| :-------------- | :----------- | :------------------------------------ |
247+
| `title` | Heading | `string` |
248+
| **`type`** (\*) | Discriminant | `'coverage'` |
249+
| **`root`** (\*) | Root folder | [CoverageTreeNode](#coveragetreenode) |
250+
251+
_(\*) Required._
252+
253+
## FileName
254+
255+
_String which matches the regular expression `/^(?!.*[ \\/:*?"<>|]).+$/` and has a minimum length of 1._
256+
257+
## FilePath
258+
259+
_String which has a minimum length of 1._
260+
183261
## Format
184262

185263
_Enum string, one of the following possible values:_
@@ -1137,27 +1215,15 @@ _Enum string, one of the following possible values:_
11371215

11381216
</details>
11391217

1140-
## OnProgress
1141-
1142-
_Function._
1143-
1144-
_Parameters:_
1145-
1146-
1. `unknown` (_optional & nullable_)
1147-
1148-
_Returns:_
1149-
1150-
- `void` (_optional_)
1151-
11521218
## PersistConfig
11531219

11541220
_Object containing the following properties:_
11551221

1156-
| Property | Description | Type |
1157-
| :---------- | :-------------------------------------- | :-------------------------------------------------------------- |
1158-
| `outputDir` | Artifacts folder | `string` (_min length: 1_) |
1159-
| `filename` | Artifacts file name (without extension) | `string` (_regex: `/^(?!.*[ \\/:*?"<>\|]).+$/`, min length: 1_) |
1160-
| `format` | | _Array of [Format](#format) items_ |
1222+
| Property | Description | Type |
1223+
| :---------- | :-------------------------------------- | :--------------------------------- |
1224+
| `outputDir` | Artifacts folder | [FilePath](#filepath) |
1225+
| `filename` | Artifacts file name (without extension) | [FileName](#filename) |
1226+
| `format` | | _Array of [Format](#format) items_ |
11611227

11621228
_All properties are optional._
11631229

@@ -1264,8 +1330,20 @@ _Object containing the following properties:_
12641330
| :-------------------- | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12651331
| **`command`** (\*) | Shell command to execute | `string` |
12661332
| `args` | | `Array<string>` |
1267-
| **`outputFile`** (\*) | Output path | `string` (_min length: 1_) |
1333+
| **`outputFile`** (\*) | Runner output path | [FilePath](#filepath) |
12681334
| `outputTransform` | | _Function:_<br /><ul><li>_parameters:_ <ol><li>`unknown` (_optional & nullable_)</li></ol></li><li>_returns:_ [AuditOutputs](#auditoutputs) _or_ _Promise of_ [AuditOutputs](#auditoutputs)</li></ul> |
1335+
| `configFile` | Runner config path | [FilePath](#filepath) |
1336+
1337+
_(\*) Required._
1338+
1339+
## RunnerFilesPaths
1340+
1341+
_Object containing the following properties:_
1342+
1343+
| Property | Description | Type |
1344+
| :-------------------------- | :----------------- | :-------------------- |
1345+
| **`runnerConfigPath`** (\*) | Runner config path | [FilePath](#filepath) |
1346+
| **`runnerOutputPath`** (\*) | Runner output path | [FilePath](#filepath) |
12691347

12701348
_(\*) Required._
12711349

@@ -1275,7 +1353,7 @@ _Function._
12751353

12761354
_Parameters:_
12771355

1278-
1. [OnProgress](#onprogress) (_optional_)
1356+
- _none_
12791357

12801358
_Returns:_
12811359

@@ -1289,7 +1367,7 @@ _Object containing the following properties:_
12891367

12901368
| Property | Description | Type |
12911369
| :-------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1292-
| **`file`** (\*) | Relative path to source file in Git repo | `string` (_min length: 1_) |
1370+
| **`file`** (\*) | Relative path to source file in Git repo | [FilePath](#filepath) |
12931371
| `position` | Location in file | _Object with properties:_<ul><li>`startLine`: `number` (_int, >0_) - Start line</li><li>`startColumn`: `number` (_int, >0_) - Start column</li><li>`endLine`: `number` (_int, >0_) - End line</li><li>`endColumn`: `number` (_int, >0_) - End column</li></ul> |
12941372

12951373
_(\*) Required._
@@ -1353,6 +1431,13 @@ Primitive row
13531431

13541432
_Array of [TableCellValue](#tablecellvalue) (\_optional & nullable_) items.\_
13551433

1434+
## Tree
1435+
1436+
_Union of the following possible types:_
1437+
1438+
- [BasicTree](#basictree)
1439+
- [CoverageTree](#coveragetree)
1440+
13561441
## UploadConfig
13571442

13581443
_Object containing the following properties:_

‎packages/models/src/index.ts

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,11 @@ export {
9797
} from './lib/reports-diff.js';
9898
export {
9999
runnerConfigSchema,
100-
runnerFunctionSchema,
101100
runnerFilesPathsSchema,
101+
runnerFunctionSchema,
102102
type RunnerConfig,
103-
type RunnerFunction,
104103
type RunnerFilesPaths,
104+
type RunnerFunction,
105105
} from './lib/runner-config.js';
106106
export {
107107
tableAlignmentSchema,
@@ -117,4 +117,18 @@ export {
117117
type TableRowObject,
118118
type TableRowPrimitive,
119119
} from './lib/table.js';
120+
export {
121+
basicTreeNodeSchema,
122+
basicTreeSchema,
123+
coverageTreeMissingLOCSchema,
124+
coverageTreeNodeSchema,
125+
coverageTreeSchema,
126+
treeSchema,
127+
type BasicTree,
128+
type BasicTreeNode,
129+
type CoverageTree,
130+
type CoverageTreeMissingLOC,
131+
type CoverageTreeNode,
132+
type Tree,
133+
} from './lib/tree.js';
120134
export { uploadConfigSchema, type UploadConfig } from './lib/upload-config.js';

‎packages/models/src/lib/audit-output.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {
77
import { errorItems, hasDuplicateStrings } from './implementation/utils.js';
88
import { issueSchema } from './issue.js';
99
import { tableSchema } from './table.js';
10+
import { treeSchema } from './tree.js';
1011

1112
export const auditValueSchema =
1213
nonnegativeNumberSchema.describe('Raw numeric value');
@@ -20,6 +21,9 @@ export const auditDetailsSchema = z.object(
2021
.array(issueSchema, { description: 'List of findings' })
2122
.optional(),
2223
table: tableSchema('Table of related findings').optional(),
24+
trees: z
25+
.array(treeSchema, { description: 'Findings in tree structure' })
26+
.optional(),
2327
},
2428
{ description: 'Detailed information' },
2529
);

‎packages/models/src/lib/implementation/schemas.ts

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,3 +223,13 @@ type Ref = { weight: number };
223223
function hasNonZeroWeightedRef(refs: Ref[]) {
224224
return refs.reduce((acc, { weight }) => weight + acc, 0) !== 0;
225225
}
226+
227+
export const filePositionSchema = z.object(
228+
{
229+
startLine: positiveIntSchema.describe('Start line'),
230+
startColumn: positiveIntSchema.describe('Start column').optional(),
231+
endLine: positiveIntSchema.describe('End line').optional(),
232+
endColumn: positiveIntSchema.describe('End column').optional(),
233+
},
234+
{ description: 'Location in file' },
235+
);

‎packages/models/src/lib/source.ts

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,13 @@
11
import { z } from 'zod';
2-
import { filePathSchema, positiveIntSchema } from './implementation/schemas.js';
2+
import {
3+
filePathSchema,
4+
filePositionSchema,
5+
} from './implementation/schemas.js';
36

47
export const sourceFileLocationSchema = z.object(
58
{
69
file: filePathSchema.describe('Relative path to source file in Git repo'),
7-
position: z
8-
.object(
9-
{
10-
startLine: positiveIntSchema.describe('Start line'),
11-
startColumn: positiveIntSchema.describe('Start column').optional(),
12-
endLine: positiveIntSchema.describe('End line').optional(),
13-
endColumn: positiveIntSchema.describe('End column').optional(),
14-
},
15-
{ description: 'Location in file' },
16-
)
17-
.optional(),
10+
position: filePositionSchema.optional(),
1811
},
1912
{ description: 'Source file location' },
2013
);

0 commit comments

Comments
 (0)