feat: support noOverwriteGlobs for templates based on react

[lmgyuan]

Description

• add noOverwriteGlobs parameters to methods saveContentToFile and saveRenderedReactContent
• pass this.noOverwriteGlobs to saveContentToFile
• check the name of file to be written against the noOverwriteGlobs to determine whether it should be actually written to the target directory
• add additional comments to relevant codes in the codebase so they are easier for future maintainers and contributors to understand.

Related issue(s)

Fixes #1128

[derberg]

@lmgyuan it's looking very good, now we just need a proper test to make sure it works long term.

Maybe we can add a test to test/integration.test.js 🤔
You could use https://github.com/asyncapi/template-for-generator-templates react-based template as a base for test. Generator template installation is npm based, so all features are included, so installing from GitHub link, pointing to specific commit will work (yes, we should not point to master to have stable tests).

This template generates a number of files -> https://github.com/asyncapi/template-for-generator-templates/blob/master/template/schemas/schema.js#L13-L20

So your test could generate output with noOverwriteGlobs ignoring some of them, and test evaluation would be as simple reading output dir and making sure that some filenames are not there. That should be reliable enough

Thoughts?

[lmgyuan]

@derberg Thanks for your comments and guidance on adding a test to the test/integration.test.js! I agree that we could add a test so we can check whether noOverwriteGlobs is working when we use React Engine. However, I am a bit confused about how to use the template-for-generator-templates. You seem to suggest that I could use https://github.com/asyncapi/template-for-generator-templates react-based template as a base for test, so do you mean something like the following:

const generator = new Generator('https://github.com/asyncapi/template-for-generator-templates.git#328', outputDir, {
      forceWrite: true,
      noOverwriteGlobs: ['**/schema.js', '**/anotherFile.js'] // Specify files to ignore
    });

There is not a specific reason for picking "#328" as the commit that this test is based on. I just picked one out of all the commits there are. I can see from the codes that the template generates a template that will generate some files, but may I ask how I could give it parameters so its output contains instructions about specific files that I want it to generate? For example, if I want the output generator template to have something like

<File name={`noOverwrite_test.html`}>
        <SchemaFile schemaName={schemaName} schema={schema} />
      </File>

so after I use the generator template to generate files, I can check that it does not overwrite noOverwrite_test.html (with --noOverwriteGlobs nOverwrite_test as a command line argument). But how do I use the template-for-generator-templates to generate the output template with instructions on file name in the first place?

Currently, instead of using template-for-generator-template, I am thinking maybe the following codes could work as a test for noOverwriteGlobs feature as well:

it('should ignore specified files with noOverwriteGlobs', async () => {
    const outputDir = generateFolderName();
    // Manually create a file to test if it's not overwritten
    const testFilePath = path.join(outputDir, 'index.html');
    // eslint-disable-next-line sonarjs/no-duplicate-string
    writeFileSync(testFilePath, '<script>const initialContent = "This should not change";</script>');

    // based on the html-template documentation, the default output is index.html
    const generator = new Generator('@asyncapi/html-template@0.28.0', outputDir, {
      forceWrite: true,
      outFilename: 'index.html',
      noOverwriteGlobs: ['**/index.html']
    });

    generator.generateFromFile(dummySpecPath);
    
    // Read the file to confirm it was not overwritten
    const fileContent = readFileSync(testFilePath, 'utf8');
    expect(fileContent).toBe('<script>const initialContent = "This should not change";</script>');
  });

Let me know what you think! : )

[derberg]

You seem to suggest that I could use https://github.com/asyncapi/template-for-generator-templates react-based template as a base for test, so do you mean something like the following:

yup exactly, just use last commit from that repo, like this

https://github.com/asyncapi/template-for-generator-templates.git#f8353637ca6bc2b4eaa5514ceb3bd06fe145e9c6

but @asyncapi/html-template@0.28.0 is good too, especially that we use it in other test cases. I like your test suggestion 💯 especially that even though 1 file is ignored, with '**/index.html' globs are still tested

go ahead with implementation please

[lmgyuan]

@derberg just update the implementation!

[derberg]

@lmgyuan you'll need to solve conflicts first before you amend your integration tests

[derberg]

why we need this?

[lmgyuan]

Deleted. I used it during development because I could not find the package.json sometimes.

[derberg]

why not log.debug = jest.fn(); and then expect(log.debug), then you do not need to do mockRestore() imho

[lmgyuan]

I tried that. jest.fn() does not work but spyOn() does. The former does not actually track the log.debug() calls in other files, but the latter does by creating a layer of observation around the existing methods.

[derberg]

expect is not async call, so no need for await

[derberg]

actually I don't get why we need to validate if it exists, if a line earlier it is created

[lmgyuan]

const generateFolderName = () => {
    // you always want to generate to new directory to make sure test runs in clear environment
    // normalize the path for cross-platform compatibility
    // return path.normalize(path.resolve(mainTestResultPath, crypto.randomBytes(4).toString('hex')));
    return path.resolve(mainTestResultPath, crypto.randomBytes(4).toString('hex'));
  };

If I understand it correctly, generateFolderName() does not actually generate the directory, but just creates and returns a path string. Thus I manually checks and creates it.

[lmgyuan]

I see that in other tests you have written, you did not check and create the directory. Did you not have directory or path not found issue? If I comment out line 78-80, I have

ENOENT: no such file or directory, open '/Users/yuanyuan/workspace/generator/test/temp/integrationTestResult/6224bfdd/test-file.md'

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud