User stories for Prototype 2 - "File-aware error reporter"

[CSchoel]

User stories for Prototype 2 - "File-aware error reporter"

I have dubbed the second prototype the "file-aware error reporter", since apart from technical issues, the main new features are file-awareness (in the sense that the server can be used when the client only knows about files and not about the model structure) and error reporting (i.e. answering a loadModel/checkModel request with LSP-compliant list of structural error messages). This prototype includes the following user stories:

• [ ] As user, I can follow a step-by-step description in the project README to compile and run the server prototype on my machine. (copied from #14)
• [ ] As user, I can find all information about possible commands and expected input for the LSP console application in the README of the project.
• [ ] As developer, I can trigger a build in GitHub actions that compiles the current version of the Mo|E server via a commit to the main branch and runs a test suite, so that I can be sure that my changes do not introduce errors. (adapted from #14)
• [ ] As developer, I can run a test suite through gradle that contains unit and/or integration tests for all major features, so that I have examples for how the project should be used and can quickly find bugs that I introduced.
  • I can't remember where I have heard this tip, but i find that a good guideline is that each unit test should be a hypothesis about errors in your code. Something like "function f will fail, if I call it with a list that is not fully sorted as its first parameter". You should be able to formulate such a hypothesis as a short sentence for each test you write and actually write that hypothesis down as a comment in the test code. This will help you to define meaningful test cases and to quickly identify which new hypotheses you haven't covered yet.
  • Suggested test hypotheses:
    • Mo|E will fail to report non-existing top-level classes.
    • Mo|E will fail to report a non-existing class within an existing top-level class.
    • Mo|E will fail to report the use of a variable that was never defined.
    • The Mo|E server process will not shut down when it receives a shutdown request.
    • When two instances of the Mo|E server are started and initialized on the same machine, they will share an OMC instance. (Which may lead to unexpected behavior)
    • ... and many more regarding much more fine-grained issues within single methods in the code.
• [ ] As Modelica programmer, I can use an LSP client to check a class in a Modelica-Project for errors, so I can identify bugs quickly and without switching tools. (#19) We do not need the full feature set here, but only the following sub-tasks:
  • Report errors as ResponseError which has additional information, such as the file name and line numbers in the data field.
  • Report errors that can occur during loadModel
  • loading a non-existing top-level class, such as FooBar
  • loading a non-existing class within an existing top-level class, such as Modelica.FooBar
  • syntax errors, such as a missing semicolon
  • Report errors that can occur during checkModel
  • variable resolution errors, such as using a variable in an equation that has no definition
• [ ] As user, I can use the LSP console application to list all classes that are defined in a Modelica file, so that I can choose freely, which of these classes I want to investigate further with other LSP commands. (This is related to the last checkbox in #19.)
• [ ] As user, I can check the correctness of all classes within the CSchoel/hh-modelica project with loadModel and checkModel (if applicable). (part of #20)
• [ ] As user, I can use the LSP console application to receive code completion suggestions based on all currently loaded classes known to the OMC, so that I can find a class through repeated completion requests without having to remember anything about its name. (related to #21)
• [ ] As user, I can use the LSP console application to shut down the server gracefully, so that all processes on the client and server side are stopped without any error messages or warnings. (Ignoring warnings does not count 😜)

[manuEbg]

The following ScriptingApiMethods might be useful to provide some "ClassCompletion". I am putting them here because its a hustle to search for them everytime...

• https://build.openmodelica.org/Documentation/OpenModelica.Scripting.searchClassNames.html (Searching classes in standardLib is very slow)
• https://build.openmodelica.org/Documentation/OpenModelica.Scripting.getAvailableLibraries.html
• https://build.openmodelica.org/Documentation/OpenModelica.Scripting.getClassInformation.html / https://build.openmodelica.org/Documentation/OpenModelica.Scripting.getClassComment.html (maybe we want to show some infos about the suggested Completions) (Both methods feel slow)
• https://build.openmodelica.org/Documentation/OpenModelica.Scripting.getClassesInModelicaPath.html (I Did not yet manage to get some kind of output from this function)

[CSchoel]

Don't forget that there are two sources where the Scripting API is documented. In the OpenModelica System Documentation there are also getPackages(), and getClassNames(), which operate on the package hierarchy and are both lightning fast and show only the top-level/direct subpackages, which may be exactly what you want for code completion.

[manuEbg]

Don't forget that there are two sources where the Scripting API is documented. In the OpenModelica System Documentation there are also getPackages(), and getClassNames(), which operate on the package hierarchy and are both lightning fast and show only the top-level/direct subpackages, which may be exactly what you want for code completion.

I have not forgotten... I think I never knew:)

For MY Interest: Scripting API doku under 2.3

BTW This whole OpenModelicaThing is absolute Madness 😂 I absolutely see why you want to simplify the whole gettingstartedprocess

[CSchoel]

Jup, the Scripting API is not exactly user friendly. :see_no_evil:

If you have any questions, feel free to ask, as I probably already went through most of the common troubles that the API has to offer.

But I have make the pedanic remark that you could have known about the OM System Documentation. I tried to compile all resources for you at the beginning of the project to minimize the development pain. :wink:

[manuEbg]

Maybe we should use publishDiagnostics instead of ResponseError to tell the Client about ModelicaCodeErrors

[manuEbg]

@CSchoel do you mind if i mark this issue as 'obsolete' and close it? I think all Points are done or in the next Prototype Issue...

[CSchoel]

No objections, go ahead. :+1: