Document how is the CLI generator discovering models and repositories in the project

[bajtos]

See #727 (comment):

I just realised that our documentation added by loopbackio/loopback.io#583 is missing an important piece of information: how is the generator discovering models and repositories in the project? What conventions does it require to work correctly?

Acceptance criteria

• In REST Controller with CRUD Methods (source), add a new subsection describing how the CLI is discovering models and repositories. What files are scanned, how are model/repository names inferred. Are we parsing the typescript to find all exports, as @loopback/boot does? Are we building the class names from file names? Are there any filters (e.g. does a repository class name have to include Repository suffix)? Etc.
• In CLI, after the user selects "REST Controller with CRUD Methods" type, but before prompting for model & repository, print a short message with a link to this new documentation. Alternatively, instead of printing this hint to all users, print it only when no models or no repositories were found. The goal is to provide a clear next step for users that run into the problem that (one of|none of) their (models|repositories) was discovered by our CLI.

[shimks]

@bajtos Please update the issue with the appropriate acceptance criteria

[bajtos]

@shimks done.

[shimks]

Rejecting based on wanting to improving the UX for this type of controller generation and wanting to leverage @loopback/boot to provide users with a list of models and repositories. This task will be blocked on the follow up task to address the issue.

EDIT: clarifying that we're rejecting this task from estimation

[bajtos]

Rejecting based on wanting to improving the UX for this type of controller generation and wanting to leverage @loopback/boot to provide users with a list of models and repositories. This task will be blocked on the follow up task to address the issue.

I disagree. Right now, people using lb4 can easily run into a problem that's difficult to troubleshoot for them. I certainly have been bitten by that.

Leveraging @loopback/boot is a great long-term solution, but that's not the point of this story! What I want to see is a small & cheap improvement that will alleviate the current source of confusion.

[shimks]

Based on the discussion brought up in estimation, it's been expressed that it feels more correct to explain how the models and repositories are discovered with how @loopback/boot discovers the artifacts to let users know the big picture of using the framework as a whole. It might be confusing for us to explain the current quickfix solution of how the CLI discovers the artifacts, when we have boot which may feel like it's related to the CLI but in reality it isn't (at least atm).

The ideal plan is to improve the documentation on trying to use all LB4 CLI tools to build a functioning lb4 project (in lieu of todo tutorial, but more CLI driven once the CLI toolings for the remaining artifacts are available). We'd like to have explanation on why and what's been generated in the artifacts created in this CLI story.

For right now, just adding links to concepts like models and repositories in the controller-generator documentation page or add a link to the tutorial which explains how models and repositories are wired up in a controller

[bajtos]

@shimks here is the (user) story I'd like to get addressed by this issue for DP3:

As a developer building a new LB4 app, I ran lb4 app to scaffold a new project. Because there is no CLI support for building models and repositories, I created my Product model and ProductRepository by hand. Unfortunately I was not aware about the strict file naming convention required by CLI, or perhaps I overlooked the differences in file names. Either way, I ended with two files - models/product.ts and repositories/product-repository.ts. Now I run lb4 controller to expose my new model via REST, but ProductRepository is not offered by the CLI tool. I am a new LB4 developer with very little knowledge about the framework, what should I do to resolve the problem?

[jannyHou]

My take of eliminating the confusion would be:

• The file naming convention should be documented under each artifact/key concept page.
• A link to an artifact's naming convention should be provided in the tutorial where we introduce using cli to create it, in a very well visible way.
• The readme document for @loopback/cli should refer to the contents above ^
  • A bonus for this issue, since users don't quite often read the readme file directly.

Thought?

[bajtos]

I am fine with describing the naming convention in our docs, as you proposed @jannyHou.

BUT: IMO, it would not occur to most people (including) myself that we need to look into README, I wouldn't be sure where to find it. Do you mean the output of lb4 controller --help? That would be a good place where to add a link to the docs too.

I still think the CLI should show some hint to the user to make it easier for them to find the documentation. At least when the CLI could not find any artifacts, it can bail out with an error message along the following lines:

No repositories found. Please make sure your project have at least on repository following the naming convention documented in {URL to docs}.