The Risk of Ignoring Check Results

Warning When ns generate is called, any modifications to the code not done correctly will be gone!

You can change anything in generated code, and it will run properly, so you may think everything is fine. The problem is that if you don't follow the rules for safe custom code, your changes will likely disappear when the code gets regenerated.

When ns generate is called, ns-flip records all of your changes, generates the code from scratch, and then reapplies your changes in their proper locations. So any modifications to the code not done correctly disappear.

Actually, there is a temporary backup directory created when you generate. Say that your code is in the directory $CODE. After running ns generate -c $CODE, a backup will be created at $CODE.backup. So if you accidentally generated without properly testing and correcting your changes, you can retrieve everything from there.

Warning: every call to ns generate $CODE wipes out the last backup and creates a new one in its place.

Using ns check

Fortunately, there's a quick sanity check built into the system: you can check your code to see whether your modifications are safe by running:

$ npx ns-flip check $CODE

Or, you can install ns-flip globally: npm i -g ns-flip. Then you can run:

$ ns check $CODE

It is advised to run test regularly.

Use Current Code

Please note that your code base must be current, or test will not work properly. By a current code base, we mean that generate was last run with the same version of $TEMPLATE and ns file that you have.

Whenever the ns file ($CODE/meta/ns.yml) changes or the contents of your $TEMPLATE change, you should run ns generate $CODE. If you don't know what that means, ask the person who built your code base, or check out building code bases. You might also be sure that you and the one who built your code base are both using the latest version of ns-flip, in the unlikely event that there were any breaking changes.

Discrepancies

If you did not pass the test because of "discrepancies", that means that you have custom code in the wrong locations. Essentially, the test command regenerates your code into the directory $CODE.test, then compares the contents to your current $CODE. There's a diffs file in $CODE.test/diffs showing any discrepancies. If you understand what's happening, the solutions to reported discrepancies are usually straightforward. But it may seem confusing at first.

If you haven't worked with diff, you may want to learn the basics.

Types of Discrepancies

Types of reported discrepancies (and their likely causes and solutions) are shown below.

  1. Your code has files that don't appear in the generated code. You need to move them to the custom directory.

  2. The generated code has files that don't appear in your code. The most likely reason is that someone deleted some files. The solution to pass the test is simply to copy them back in from the $CODE.test directory. The exact path of the missing file is given in the diffs file. Technically, missing unused files don't pose a problem, because they are simply regenerated. But by the same token the deletion did not get rid of the unwanted file. Probably the core reason is that you replaced them with custom code (hopefully in the custom directory) that replaced them. The preferred solution could be replacement of sections in the deleted files, possibly incorporating custom code into designated custom code sections or components programmed inside the custom directory.

  3. Lines in the generated test code do not appear in yours. That would indicate that you removed some code. The solution is to add those lines to your code in the line number indicated, and then to try the test again. To remove code properly, you need to replace an entire designated section with an empty version, as explained in Replacement Code. If no appropriate section exists, you may have to replace a larger section. You probably should also contact the template maintainer and suggest adding a new section if you think that the removal would be needed in a number of code bases.

  4. Your code has lines not in the generated code. That usually indicates that you added code in places not permitted in the code. You need to insert all of your custom code in designated custom code sections, or to replace a section of the generated code using the replacement delimiter. It's always preferred to place code into a custom area rather than replacing, but if you must then replacement works.

  5. Your code is simply different. That situation may arise from one of two situations:

    (a) Linting discrepancies. You may simply need to lint your code and remove linting errors. For instance, it could be that your code using a double quote and the generated code uses a single quote. Hopefully your code base has a proper linting file and maybe even is running something automatic like prettier.

    (b) Your code may have missing or altered comment lines for delimiting sections or custom code areas. That can happen if you accidentally affected one. You may have to look at the generated code a bit to identify the discrepancies.