Configurable rule on Paths subject

[adamaltman]

[UPDATED - SOLVED]

I'm trying to write a configurable rule to enforce if two consecutive path segments don't have a variable.

For example, good: /orgs/{orgId}/widgets
For example, good: /orgs/{orgId}/widgets/{widgetId}
For example, bad: /orgs/{orgId}/foobar/widgets
For example, bad: /orgs/{orgId}/foobar/widgets/{widgetId}

This is the solution (verified it works) 🎉 :

  rule/restful-paths-second-try:
    subject: 
      type: PathItem
      matchParentKeys: '/[^{/}]+/[^{/}]+/'
    assertions: 
      defined: false
    message: (PathItem) Two consecutive path segments don't have a variable

It reports 22 problems in the API I'm reviewing, which is what I expected (more or less). However, for some reason the VS Code extension doesn't report these problems (I even restarted 🤣 ).

Previous attempts

I had a few previous attempts.

Wrong pattern close

I came up with this pattern /[^{/}]+/[^{/}]+ to detect the issue. But it needs to run on each path. This doesn't work:

  rule/restful-paths:
    subject: 
      type: Paths
    assertions: 
      notPattern: /[^{/}]+/[^{/}]+
    message: Two consecutive path segments don't have a variable

I missed closing the pattern with /. This caused a hard fail of sorts that was surpressed in VS code but displays on the CLI output when running lint:

% redocly lint
validating /blue-harvest/openapi/openapi.yaml...
Syntax error: Invalid flags supplied to RegExp constructor '}]+' SyntaxError: Invalid flags supplied to RegExp constructor '}]+'
    at new RegExp (<anonymous>)
    at Object.regexFromString (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/rules/common/assertions/utils.js:209:23)
    at Object.notPattern (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/rules/common/assertions/asserts.js:54:31)
    at runAssertion (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/rules/common/assertions/utils.js:203:46)
    at applyAssertions (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/rules/common/assertions/utils.js:60:32)
    at /Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/rules/common/assertions/utils.js:115:26
    at visitWithContext (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/walk.js:239:13)
    at walkNode (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/walk.js:132:29)
    at walkNode (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/walk.js:187:25)
    at Object.walkDocument (/Users/adam/.nvm/versions/node/v18.15.0/lib/node_modules/@redocly/cli/node_modules/@redocly/openapi-core/lib/walk.js:32:5)

Subject reporting granularity issue

This probably works but only 1 problem is reported.

  rule/restful-paths:
    subject: 
      type: Paths
    assertions: 
      notPattern: '/[^{/}]+/[^{/}]+/'
    message: Two consecutive path segments don't have a variable

Reasons for this rule

Certainly! Let's break down the requirement:

1. A path segment is defined by a string between slashes (/).
2. A segment with a variable is represented by curly braces, like {variable}.
3. The pattern is considered bad if two consecutive path segments don't have a variable.

Based on this, we can design the regex:

• A non-variable segment can be represented as: [^{/}]+. This matches any string that doesn't contain a / or { or }.
• Two consecutive non-variable segments would then be: [^{/}]+/[^{/}]+.

The full regex pattern to detect the bad pattern is:

/[^{/}]+/[^{/}]+

Here's a brief explanation:

• /[^{/}]+/: matches a slash, followed by any number of characters that are not slashes or curly braces, followed by another slash.
• [^{/}]+: matches any number of characters that are not slashes or curly braces.

Using this regex pattern, you can detect paths that have two consecutive path segments without variables. If a match is found, then it's a bad pattern.

Let's test this on the provided examples to see if it works:

The results are as expected:

• good_example: No match (indicating it's a good pattern).
• bad_example1: Match found (indicating it's a bad pattern).
• bad_example2: Match found (indicating it's a bad pattern).

You can use the regex pattern /[^{/}]+/[^{/}]+ in an ECMAScript-compatible environment to detect paths with two consecutive segments without variables. If the regex finds a match, then it's a bad pattern.