feat: implemented new linting of entities to support new scorecards by AlbinaBlazhko17 · Pull Request #2495 · Redocly/redocly-cli

AlbinaBlazhko17 · 2026-01-12T14:57:10Z

What/Why/How?

Implemented lintEntityWithScorecardLevel, which will be used in portal to lint new entities with new scorecard functionality.
Implemented lintSchema for linting specific schema. If entity has data-schema type we need to lint only provided schema.
Added support for Assertions (custom rules) in lintEntityFile.
The main goal of helper functions are to transform assertion subject to type, which is provided in @redocly/config.
Changed json-schema-adapter.ts to handle nodeTypeName if provided. Added returning of discriminatorFunc from adapter to get proper rootType. Added functionality to discriminatorFunc for handling mapping the default naming and provided nodeTypeName.
Fixed tests to match new structure.

Opened questions:

How to handle entities with the type of api-operations.
Adding support of custom rules for arrays. Currently, we don't have any Assertions (e.g. lt, lte, gte, etc.) for arrays.

Reference

Testing

Ran tests in CLI and Realm.

Screenshots (optional)

Check yourself

Code changed? - Tested with Redoc/Realm/Reunite (internal)
All new/updated code is covered by tests
New package installed? - Tested in different environments (browser/node)
Documentation update considered

Security

The security impact of the change has been considered
Code follows company security practices and guidelines

changeset-bot · 2026-01-12T14:57:14Z

🦋 Changeset detected

Latest commit: 475e9f8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	Minor
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-01-13T10:34:32Z

CLI Version	Mean Time ± Std Dev (s)	Relative Performance (Lower is Faster)
cli-latest	3.587s ± 0.042s	▓ 1.00x (Fastest)
cli-next	3.590s ± 0.042s	▓ 1.00x

github-actions · 2026-01-13T10:34:33Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	79.33% (🎯 78%)	6249 / 7877
🔵	Statements	78.74% (🎯 78%)	6455 / 8197
🔵	Functions	82.96% (🎯 81%)	1271 / 1532
🔵	Branches	71.05% (🎯 70%)	4301 / 6053

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/lint.ts	94.5%	81.53%	100%	94.38%	128-139, 162, 359, 363-365
packages/core/src/types/entity-yaml.ts	100%	100%	100%	100%
packages/core/src/types/json-schema-adapter.ts	84.84%	82.17%	100%	84.04%	22, 40, 44, 48, 52-54, 76, 80, 98, 106-108, 112-114, 136, 158, 162, 166, 170-172
packages/core/src/types/redocly-yaml.ts	92.3%	82.85%	100%	91.93%	357, 359, 411, 414, 417
packages/core/src/utils/scorecards.ts	88.88%	84.84%	90.9%	90.9%	39, 78, 86, 97, 120-126

Generated in workflow #8440 for commit 475e9f8 by the Vitest Coverage Report Action

tatomyr · 2026-02-04T12:27:36Z

packages/core/src/__tests__/entity-yaml.test.ts


    expect(resolvedType).toBeTruthy();
-    expect(resolvedType.name).toBe('EntityFileDefault');
+    expect(resolvedType.name).toBe('UserEntity'); // Falls back to first type when discriminator fails


Maybe it's better to put Entity first, so it becomes the default fallback?

tatomyr · 2026-02-04T12:28:29Z

packages/core/src/__tests__/entity-yaml.test.ts

+    const { lintEntityFile } = await import('../lint.js');
+    const { makeDocumentFromString, BaseResolver } = await import('../resolve.js');
+
+    const entities = `- type: user


Could you use outdent?

tatomyr · 2026-02-04T12:31:05Z

packages/core/src/__tests__/entity-yaml.test.ts

+    expect(entityTypes).toHaveProperty('DomainEntity');
+    expect(entityTypes).toHaveProperty('TeamEntity');
+    expect(entityTypes).toHaveProperty('Entity');
    expect(entityTypes).toHaveProperty('EntityFileArray');


WHy don't we expect EntityFile/Default anymore?

I see we use them in createEntityTypes.

tatomyr · 2026-02-04T12:33:09Z

packages/core/src/types/json-schema-adapter.ts

-          const discriminatedTypeName = value[discriminatedPropertyName];
-          if (typeof discriminatedTypeName === 'string' && ctx[discriminatedTypeName]) {
-            return discriminatedTypeName;
+          const discriminatorValue = value[discriminatedPropertyName];


Why changed discriminatedTypeName -> discriminatorValue? It's still a property name, not a value. Or am I missing something?

tatomyr · 2026-02-04T12:36:01Z

packages/core/src/types/json-schema-adapter.ts

+
+        // Store mapping from discriminator value to actual type name
+        if (typeof actualTypeName === 'string') {
+          discriminatorMapping[discriminatorValue] = actualTypeName;


Not sure why do we need to mutate it here. Don't we receive the discriminator mapping in the needed form already?

tatomyr · 2026-02-04T13:10:59Z

packages/core/src/utils/scorecards.ts

+    typeof parsed === 'object' &&
+    parsed !== null &&


Suggested change

typeof parsed === 'object' &&

parsed !== null &&

isPlainObject(parsed)

tatomyr · 2026-02-04T13:14:33Z

packages/core/src/lint.ts

  entityDefaultSchema: JSONSchema;
  severity?: ProblemSeverity;
  externalRefResolver?: BaseResolver;
+  assertionConfig?: Record<string, Assertion>;


Assertions should be converted a separate array, at least it's so for regular lint. Let's discuss this offline.

tatomyr · 2026-02-04T13:16:41Z

packages/core/src/lint.ts

+  }
+
+  const externalRefResolver = new BaseResolver();
+  const entityDocument = makeDocumentFromString(JSON.stringify(entity, null, 2), 'entity.yaml');


Why do we need to create a fake entity file on the fly? We should be able to resolve the real files.

tatomyr · 2026-02-04T13:18:42Z

packages/core/src/lint.ts

+    });
+
+    return [...entityProblems, ...apiProblems];
+  } else if (Object.keys(apiRules).length !== 0) {


Please use a utility function if possible (isEmptyObject or something like that).

tatomyr · 2026-02-04T13:20:05Z

packages/core/src/utils/scorecards.ts

+  return subjectType;
+}
+
+export function transformScorecardRulesToAssertions(


Why not use the existing assertion/rules conversion mechanism?

AlbinaBlazhko17 self-assigned this Jan 26, 2026

AlbinaBlazhko17 requested a review from RomanHotsiy January 26, 2026 17:46

AlbinaBlazhko17 marked this pull request as ready for review January 26, 2026 17:56

AlbinaBlazhko17 requested review from a team as code owners January 26, 2026 17:56

JLekawa approved these changes Jan 26, 2026

View reviewed changes

AlbinaBlazhko17 mentioned this pull request Jan 30, 2026

chore: update redocly config to v0.41.3 #2522

Merged

6 tasks

AlbinaBlazhko17 added 16 commits January 30, 2026 10:44

feat: initial implementation to support new scorecards and entities

8a7ebb5

feat: add support for default rules

083a3ad

feat: implement functionality to find data-schema and validate only it

5716446

fix: types in document and imports

f179e9a

fix: failing unit tests

c1cfa32

refactor: divide functions into proper folders, fix types and exports

a707e9a

feat: add functionality to re-map nodeTypes to support assertions

2b15dfe

refactor: transfrom functions using type from config

ed7140a

fix: unit tests and add one test to cover array of entities

4c8bd3a

refactor: remove unused function

7c7ff89

refactor: basic functionality

e747095

fix: return type in lintEntityByScorecardLevel

3428bcf

feat: add tests for lintEntityByScorecardLevel function

84a1c67

chore: revert changes for testing

8917986

chore: add changeset

31c27c1

refactor: naming and findDataSchemaInDocument function

475e9f8

AlbinaBlazhko17 force-pushed the feat/new-scorecard-pitch branch from bb3606d to 475e9f8 Compare January 30, 2026 08:46

tatomyr reviewed Feb 4, 2026

View reviewed changes

	typeof parsed === 'object' &&
	parsed !== null &&
	isPlainObject(parsed)

Conversation

AlbinaBlazhko17 commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Opened questions:

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot bot commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlbinaBlazhko17 commented Jan 12, 2026 •

edited

Loading

changeset-bot bot commented Jan 12, 2026 •

edited

Loading

github-actions bot commented Jan 13, 2026 •

edited

Loading

github-actions bot commented Jan 13, 2026 •

edited

Loading