Redocly / Redocly/redocly-cli

Add option `--prefix-components-with-filepath` to `join`

Open
#1,575 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

p3 Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Is your feature request related to a problem? Please describe.

This is a follow-up to #1566:

When you have nested component references, the names of the components can quickly collide.

Currently the only options are:

  • uniquely name all components (which is a big code smell in my opinion - the file is already a namespace)
  • or you use --prefix-components-with-info-prop, which can blow up your joined yaml by duplicated components. (I suppose this will grow exponentially with each layer of referenced file.)

Describe the solution you'd like

I would like to get a new option in, lets call it --prefix-components-with-filepath that has three values:

  • auto: (default) will optionally prefix the components with pieces of the filename + path until it is unique
  • name: will always prefix the components with the filename and then optionally add parts of the path until it is unique
  • full: will always prefix the component with the filename plus its path up to the project's root

Technically, the file paths of each component name should be resolved to their realpath, and then cut off starting at the root until uniqueness of the prefix is compromised. This should avoid confusion when different folder depths are involved.

So imagine in all my join sources I'm referencing these components:

  • my/schema/a/foo.yml#/definitions/getRequest
  • my/schema/b/foo.yml#/definitions/getRequest
  • my/bar.yml#/definitions/getRequest
  • my/schema/a/foo.yml#/definitions/postBody
  • my/schema/bar.yml#/definitions/postBody
  • my/schema/a/foo.yml#/definitions/someCompUniqueToAFoo
  • my/schema/b/foo.yml#/definitions/someCompUniqueToBFoo

The resulting component names would be as follow:

  • --prefix-components-with-filepath auto:
    • schema_a_foo_getRequest
    • schema_b_foo_getRequest
    • bar_getRequest
    • a_foo_postBody
    • bar_postBody
    • someCompUniqueToAFoo
    • someCompUniqueToBFoo
  • --prefix-components-with-filepath name:
    • schema_a_foo_getRequest
    • schema_b_foo_getRequest
    • bar_getRequest
    • a_foo_postBody
    • bar_postBody
    • foo_someCompUniqueToAFoo
    • foo_someCompUniqueToBFoo
  • --prefix-components-with-filepath full:
    • my_schema_a_foo_getRequest
    • my_schema_b_foo_getRequest
    • my_bar_getRequest
    • my_schema_a_foo_postBody
    • my_schema_bar_postBody
    • my_schema_a_foo_someCompUniqueToAFoo
    • my_schema_b_foo_someCompUniqueToBFoo

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the join command and follow-up issue #1566, then inspect how nested component references and the existing --prefix-components-with-info-prop option are handled. Done means the new option supports auto, name, and full modes and produces component names matching the examples for the referenced file paths.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.