@itee/tasks 1.0.12

package/sources/index.mjs

@@ -0,0 +1,21 @@
+export { buildTask }                           from './builds/build.task.mjs'
+export { cleanTask }                           from './cleans/clean.task.mjs'
+export { docTask }                             from './docs/doc.task.mjs'
+export { helpTask }                            from './helps/help.task.mjs'
+export { lintTask }                            from './lints/lint.task.mjs'
+export { releaseTask }                         from './releases/release.task.mjs'
+export { runTestsTask }                        from './tests/run-tests.task.mjs'
+export { computeUnitTestsTask }                from './tests/units/compute-unit-tests.task.mjs'
+export { runUnitTestsTask }                    from './tests/units/run-unit-tests.task.mjs'
+export { runUnitTestsForBackendTask }          from './tests/units/run-unit-tests-for-backend.task.mjs'
+export { runUnitTestsForFrontendTask }         from './tests/units/run-unit-tests-for-frontend.task.mjs'
+export { checkBundlingFromEsmBuildImportTask } from './tests/bundlings/check-bundling-from-esm-build-import.task.mjs'
+export { checkBundlingFromEsmFilesDirectTask } from './tests/bundlings/check-bundling-from-esm-files-direct.task.mjs'
+export { checkBundlingFromEsmFilesImportTask } from './tests/bundlings/check-bundling-from-esm-files-import.task.mjs'
+export { checkBundlingTask }                   from './tests/bundlings/check-bundling.task.mjs'
+export { computeBenchmarksTask }               from './tests/benchmarks/compute-benchmarks.task.mjs'
+export { runBenchmarksTestsTask }              from './tests/benchmarks/run-benchmarks.task.mjs'
+export { runBenchmarksForBackendTask }         from './tests/benchmarks/run-benchmarks-for-backend.task.mjs'
+export { runBenchmarksForFrontendTask }        from './tests/benchmarks/run-benchmarks-for-frontend.task.mjs'
+
+export * from './_utils.mjs'

package/sources/lints/lint.task.mjs

@@ -0,0 +1,46 @@
+import colors        from 'ansi-colors'
+import log           from 'fancy-log'
+import child_process from 'node:child_process'
+import { basename }  from 'node:path'
+import { promisify } from 'node:util'
+import {
+    getTaskConfigurationPathFor,
+    logLoadingTask
+}                    from '../_utils.mjs'
+
+logLoadingTask( import.meta.filename )
+
+const execFile = promisify( child_process.execFile )
+const { red }  = colors
+
+/**
+ * @method npm run lint
+ * @global
+ * @description Will lint the sources files and try to fix the style when possible
+ */
+const lintTask       = async ( done ) => {
+
+    try {
+
+        const configurationPath = getTaskConfigurationPathFor( import.meta.filename )
+
+        const { stdout } = await execFile( 'npx', [ 'eslint', '--config', configurationPath, '--fix' ] )
+        if ( stdout !== '' ) {
+            log( stdout )
+        }
+
+        done()
+
+    } catch ( error ) {
+
+        log( error.stdout )
+        done( red( error.message ) )
+
+    }
+
+}
+lintTask.displayName = basename( import.meta.filename, '.task.mjs' )
+lintTask.description = 'Will lint the sources files and try to fix the style when possible.'
+lintTask.flags       = null
+
+export { lintTask }

package/sources/refresh.mjs

@@ -0,0 +1,100 @@
+import colors            from 'ansi-colors'
+import log               from 'fancy-log'
+import { writeFileSync } from 'fs'
+import {
+    basename,
+    join,
+    relative
+}                        from 'path'
+import {
+    getFilesFrom,
+    getTaskConfigurationFor,
+    iteePackageRootDirectory,
+    iteePackageSourcesDirectory,
+    packageNodeModulesDirectory,
+    packageRootDirectory,
+    packageTasksDirectory
+}                        from './_utils.mjs'
+
+const {
+          green,
+          yellow
+      } = colors
+
+const configuration = await getTaskConfigurationFor( import.meta.filename )
+
+// Get and filter tasks to expose
+const defaultTaskPattern = join( iteePackageSourcesDirectory, '/{*.task.mjs,**/*.task.mjs,**/**/*.task.mjs}' )
+const defaultTaskFiles   = getFilesFrom(
+    defaultTaskPattern,
+    filePath => {
+        const relativeFilepath = relative( iteePackageSourcesDirectory, filePath )
+        const filename         = basename( filePath )
+        const included         = !configuration.includes( filename )
+
+        included
+        ? log( 'Include default task from', green( relativeFilepath ) )
+        : log( 'Exclude default task from', yellow( relativeFilepath ) )
+
+        return included
+    }
+)
+
+const userTaskPattern = join( packageTasksDirectory, '/{*.task.mjs,**/*.task.mjs,**/**/*.task.mjs}' )
+const userTaskFiles   = getFilesFrom(
+    userTaskPattern,
+    filePath => {
+        const relativeFilepath = relative( packageRootDirectory, filePath )
+        const filename         = basename( filePath )
+        const included         = !configuration.includes( filename )
+
+        included
+        ? log( 'Include user task from', green( relativeFilepath ) )
+        : log( 'Exclude user task from', yellow( relativeFilepath ) )
+
+        return included
+    }
+)
+
+// Prepare gulpfile content with header
+let gulpfileContent = '' +
+    '/**\n' +
+    ' * This file is auto-generated by internal gulp command.\n' +
+    ' * If you want to customize the available gulp tasks, create your own in .tasks folder\n' +
+    ' * and run "gulp refresh"\n' +
+    ' */\n\n'
+
+// Generate default tasks exports and append to gulpfile content
+gulpfileContent += '// Default Itee tasks\n'
+for ( const taskFile of defaultTaskFiles ) {
+
+    // we are calling from client and use relative path from it
+    if ( iteePackageRootDirectory.includes( 'node_modules' ) ) {
+
+        const relativeTaskFile = relative( packageNodeModulesDirectory, taskFile )
+        gulpfileContent += `export * from '${ relativeTaskFile }'\n`
+
+    } else { // we are refreshing itee-tasks package internally
+
+        const relativeTaskFile = relative( iteePackageRootDirectory, taskFile )
+        gulpfileContent += `export * from './${ relativeTaskFile }'\n`
+
+    }
+
+}
+
+gulpfileContent += '\n'
+
+// Generate user tasks exports and append to gulpfile content
+if ( userTaskFiles.length > 0 ) {
+    gulpfileContent += '// User defined tasks\n'
+}
+for ( const taskFile of userTaskFiles ) {
+    const relativeTaskFile = relative( packageRootDirectory, taskFile )
+    gulpfileContent += `export * from './${ relativeTaskFile }'\n`
+}
+
+// Create gulpfile file
+const gulpfilePath = join( packageRootDirectory, 'gulpfile.mjs' )
+log( 'Refresh', green( gulpfilePath ) )
+writeFileSync( gulpfilePath, gulpfileContent )

package/sources/releases/release.task.mjs

@@ -0,0 +1,32 @@
+import { series }                from 'gulp'
+import { basename }              from 'node:path'
+import { logLoadingTask }        from '../_utils.mjs'
+import { buildTask }             from '../builds/build.task.mjs'
+import { cleanTask }             from '../cleans/clean.task.mjs'
+import { docTask }               from '../docs/doc.task.mjs'
+import { lintTask }              from '../lints/lint.task.mjs'
+import { computeBenchmarksTask } from '../tests/benchmarks/compute-benchmarks.task.mjs'
+import { runTestsTask }          from '../tests/run-tests.task.mjs'
+import { computeUnitTestsTask }  from '../tests/units/compute-unit-tests.task.mjs'
+
+logLoadingTask( import.meta.filename )
+
+/**
+ * @method npm run release
+ * @global
+ * @description Will perform a complete release of the library including 'clean', 'lint', 'doc', 'build-tests', 'test' and finally 'build'.
+ */
+const releaseTask       = series(
+    cleanTask,
+    buildTask,
+    computeBenchmarksTask,
+    computeUnitTestsTask,
+    runTestsTask,
+    lintTask,
+    docTask,
+)
+releaseTask.displayName = basename( import.meta.filename, '.task.mjs' )
+releaseTask.description = 'Will perform a complete release of the library including \'clean\', \'lint\', \'doc\', \'test\' and finally \'build\'.'
+releaseTask.flags       = null
+
+export { releaseTask }

package/sources/tests/benchmarks/compute-benchmarks.task.mjs

@@ -0,0 +1,236 @@
+import colors       from 'ansi-colors'
+import childProcess from 'child_process'
+import log          from 'fancy-log'
+import { glob }     from 'glob'
+import {
+    basename,
+    dirname,
+    extname,
+    join,
+    normalize,
+    relative
+}                   from 'path'
+import {
+    createDirectoryIfNotExist,
+    createFile,
+    getTaskConfigurationFor,
+    logLoadingTask,
+    packageName,
+    packageNodeModulesDirectory,
+    packageSourcesDirectory,
+    packageTestsBenchmarksDirectory,
+    packageTestsDirectory
+}                   from '../../_utils.mjs'
+
+logLoadingTask( import.meta.filename )
+
+const {
+          red,
+          yellow,
+      } = colors
+
+/**
+ * @description Will generate benchmarks files from source code against provided alternatives
+ */
+const computeBenchmarksTask       = async ( done ) => {
+
+    createDirectoryIfNotExist( packageTestsBenchmarksDirectory )
+
+    // Get task configuration
+    const filePathsToIgnore = await getTaskConfigurationFor( import.meta.filename )
+
+    // Get source files to process
+    const pattern     = join( packageSourcesDirectory, '**' )
+    const sourceFiles = glob.sync( pattern )
+                            .map( filePath => normalize( filePath ) )
+                            .filter( filePath => {
+                                const fileName         = basename( filePath )
+                                const isJsFile         = fileName.endsWith( '.js' )
+                                const isNotPrivateFile = !fileName.startsWith( '_' )
+                                const isNotIgnoredFile = !filePathsToIgnore.includes( fileName )
+                                return isJsFile && isNotPrivateFile && isNotIgnoredFile
+                            } )
+
+    const benchRootImports = []
+    for ( let sourceFile of sourceFiles ) {
+
+        const specificFilePath = sourceFile.replace( packageSourcesDirectory, '' )
+        const specificDir      = dirname( specificFilePath )
+
+        const fileName      = basename( sourceFile, extname( sourceFile ) )
+        const benchFileName = `${ fileName }.bench.js`
+        const benchDirPath  = join( packageTestsBenchmarksDirectory, specificDir )
+        const benchFilePath = join( benchDirPath, benchFileName )
+
+        const nsName         = `${ fileName }Namespace`
+        const importDirPath  = relative( benchDirPath, packageSourcesDirectory )
+        const importFilePath = join( importDirPath, specificFilePath ).replace( /\\/g, '/' )
+
+        try {
+
+            const jsdocPath   = join( packageNodeModulesDirectory, '/jsdoc/jsdoc.js' )
+            const jsdocOutput = childProcess.execFileSync( 'node', [ jsdocPath, '-X', sourceFile ] ).toString()
+
+            const classNames    = []
+            const usedLongnames = []
+            const jsonData      = JSON.parse( jsdocOutput ).filter( data => {
+
+                const longName = data.longname
+
+                const kind = data.kind
+                if ( kind !== 'function' ) {
+                    if ( kind === 'class' && !classNames.includes( longName ) ) {
+                        classNames.push( longName )
+                    }
+                    return false
+                }
+
+                // We don't care that data bloc have comment they are unused to generate benchmarks
+                // const undocumented = data.undocumented
+                // if ( undocumented ) {
+                //     return false
+                // }
+
+                const scope = data.scope
+                if ( ![ 'global', 'static' ].includes( scope ) ) {
+                    return false
+                }
+
+                if ( longName.includes( ' ' ) || longName.includes( '~' ) || usedLongnames.includes( longName ) ) {
+                    return false
+                }
+
+                for ( let className of classNames ) {
+                    if ( longName.includes( className ) ) {
+                        return false
+                    }
+                }
+
+                usedLongnames.push( longName )
+
+                return true
+
+            } )
+
+            if ( jsonData.length === 0 ) {
+                log( 'Ignoring', yellow( `${ sourceFile }, no usable exports found` ) )
+                continue
+            }
+
+            // Compute benchmark suites by grouping logically function by name[_x]
+            const suiteGroups = {}
+            for ( let docData of jsonData ) {
+
+                try {
+
+                    const functionName = docData.name
+                    const nameSplits   = functionName.split( '_' )
+                    const rootName     = nameSplits[ 0 ]
+
+                    if ( !( rootName in suiteGroups ) ) {
+                        suiteGroups[ rootName ] = []
+                    }
+
+                    suiteGroups[ rootName ].push( functionName )
+
+                } catch ( error ) {
+
+                    log( red( error.message ) )
+
+                }
+
+            }
+
+            // Generate suites
+            let benchSuites       = ''
+            const suitesToExports = []
+            for ( let suiteGroupName in suiteGroups ) {
+                suitesToExports.push( `${ suiteGroupName }Suite` )
+                benchSuites += `const ${ suiteGroupName }Suite = Benchmark.Suite( '${ nsName }.${ suiteGroupName }', Testing.createSuiteOptions() )` + '\n'
+
+                for ( let suiteGroupValue of suiteGroups[ suiteGroupName ] ) {
+                    benchSuites += `                                     .add( '${ suiteGroupValue }()', Testing.iterateOverDataMap( ${ nsName }.${ suiteGroupValue } ), Testing.createBenchmarkOptions() )` + '\n'
+                }
+
+                benchSuites += '\n'
+            }
+
+            // compute relative level to get import wrappers
+            const wrapperDirPath          = relative( benchDirPath, packageTestsDirectory )
+            const importBenchmarkFilePath = join( wrapperDirPath, 'import.benchmarks.js' )
+            const importTestingFilePath   = join( wrapperDirPath, 'import.testing.js' )
+
+            const template = '' +
+                `import * as ${ nsName } from '${ importFilePath }'` + '\n' +
+                `import { getBenchmarkPackage } from '${ importBenchmarkFilePath }'` + '\n' +
+                `import { getTestingPackage } from '${ importTestingFilePath }'` + '\n' +
+                '\n' +
+                `const Benchmark = await getBenchmarkPackage()` + '\n' +
+                `const Testing   = await getTestingPackage()` + '\n' +
+                '\n' +
+                `${ benchSuites }` +
+                // '\n' +
+                `export { ${ suitesToExports } }` + '\n' +
+                '\n'
+
+            const importBenchFilePath = relative( packageTestsBenchmarksDirectory, benchFilePath ).replace( /\\/g, '/' )
+            benchRootImports.push( {
+                path:    importBenchFilePath,
+                exports: suitesToExports
+            } )
+
+            createDirectoryIfNotExist( benchDirPath )
+            createFile( benchFilePath, template )
+
+        } catch ( error ) {
+
+            log( red( error.message ) )
+
+        }
+
+    }
+
+    let templateImports = ''
+    let suites          = []
+    for ( let i = 0 ; i < benchRootImports.length ; i++ ) {
+
+        const currentBench = benchRootImports[ i ]
+        const namedExports = currentBench.exports
+        const imports      = namedExports.join( ', ' )
+        suites.push( ...namedExports )
+
+        templateImports += `import {${ imports }} from './${ currentBench.path }'` + '\n'
+
+    }
+
+    // Use a fallback in case no benches were found at all
+    if ( benchRootImports.length === 0 ) {
+        log( 'Warning ', yellow( 'No usable exports found, generate default file to avoid frontend breakage.' ) )
+        const defaultBenchesDir  = join( packageTestsBenchmarksDirectory, 'default' )
+        const defaultBenchesPath = join( defaultBenchesDir, 'default.bench.js' )
+
+        createDirectoryIfNotExist( defaultBenchesDir )
+        createFile( defaultBenchesPath, '// Avoid web test runner crash on empty benches' )
+    }
+
+    const benchesTemplate = '' +
+        `${ templateImports }` + '\n' +
+        'const suites = [' + '\n' +
+        `${ suites.map( suite => `\t${ suite }` ).join( ',\n' ) }` + '\n' +
+        ']' + '\n' +
+        '\n' +
+        `for ( const suite of suites ) {` + '\n' +
+        `\tsuite.run()` + '\n' +
+        `}` + '\n'
+
+    const benchesFilePath = join( packageTestsBenchmarksDirectory, `${ packageName }.benchmarks.js` )
+    createFile( benchesFilePath, benchesTemplate )
+
+    done()
+
+}
+computeBenchmarksTask.displayName = basename( import.meta.filename, '.task.mjs' )
+computeBenchmarksTask.description = 'Will generate benchmarks files from source code against provided alternatives.'
+computeBenchmarksTask.flags       = null
+
+export { computeBenchmarksTask }

package/sources/tests/benchmarks/run-benchmarks-for-backend.task.mjs

@@ -0,0 +1,43 @@
+import colors         from 'ansi-colors'
+import log            from 'fancy-log'
+import { existsSync } from 'fs'
+import { basename }   from 'node:path'
+import { join }       from 'path'
+import {
+    logLoadingTask,
+    packageName,
+    packageTestsBenchmarksDirectory
+}                     from '../../_utils.mjs'
+
+logLoadingTask( import.meta.filename )
+
+const {
+          red,
+          yellow
+      } = colors
+
+/**
+ * @description Will run benchmarks with node
+ */
+const runBenchmarksForBackendTask       = async ( done ) => {
+
+    const benchesPath = join( packageTestsBenchmarksDirectory, `/${ packageName }.benchmarks.js` )
+    if ( !existsSync( benchesPath ) ) {
+        log( yellow( `${ benchesPath } does not exist, skip backend benchmarks...` ) )
+        done()
+        return
+    }
+
+    try {
+        await import(benchesPath)
+        done()
+    } catch ( error ) {
+        done( red( error ) )
+    }
+
+}
+runBenchmarksForBackendTask.displayName = basename( import.meta.filename, '.task.mjs' )
+runBenchmarksForBackendTask.description = 'Will run benchmarks with node'
+runBenchmarksForBackendTask.flags       = null
+
+export { runBenchmarksForBackendTask }

package/sources/tests/benchmarks/run-benchmarks-for-frontend.task.mjs

@@ -0,0 +1,48 @@
+import { startTestRunner } from '@web/test-runner'
+import colors              from 'ansi-colors'
+import { basename }        from 'node:path'
+import {
+    getTaskConfigurationFor,
+    logLoadingTask
+}                          from '../../_utils.mjs'
+
+logLoadingTask( import.meta.filename )
+
+const { red } = colors
+
+/**
+ * @description Will run benchmarks with web-test-runner
+ */
+const runBenchmarksForFrontendTask       = () => {
+    return new Promise( async ( resolve, reject ) => {
+
+        const configuration = await getTaskConfigurationFor( import.meta.filename )
+        const testRunner    = await startTestRunner( {
+            config:          configuration,
+            readCliArgs:     false,
+            readFileConfig:  false,
+            autoExitProcess: false,
+        } )
+
+        if ( !testRunner ) {
+            reject( red( 'Internal test runner error.' ) )
+            return
+        }
+
+        // To ensure that testRunner exit event won't be used by other instance of test runner,
+        // we need to be sure that current test runner is ended
+        testRunner.on( 'finished', () => {
+            testRunner.stop()
+        } )
+
+        testRunner.on( 'stopped', () => {
+            resolve()
+        } )
+
+    } )
+}
+runBenchmarksForFrontendTask.displayName = basename( import.meta.filename, '.task.mjs' )
+runBenchmarksForFrontendTask.description = 'Will run benchmarks with web-test-runner.'
+runBenchmarksForFrontendTask.flags       = null
+
+export { runBenchmarksForFrontendTask }

package/sources/tests/benchmarks/run-benchmarks.task.mjs

@@ -0,0 +1,16 @@
+import { basename } from 'node:path'
+import {
+    getTaskConfigurationFor,
+    logLoadingTask,
+    serializeTasksFrom
+}                   from '../../_utils.mjs'
+
+logLoadingTask( import.meta.filename )
+
+const configuration                = await getTaskConfigurationFor( import.meta.filename )
+const runBenchmarksTestsTask       = await serializeTasksFrom( configuration )
+runBenchmarksTestsTask.displayName = basename( import.meta.filename, '.task.mjs' )
+runBenchmarksTestsTask.description = 'Will run benchmarks in back and front environments.'
+runBenchmarksTestsTask.flags       = null
+
+export { runBenchmarksTestsTask }

package/sources/tests/bundlings/check-bundling-from-esm-build-import.task.mjs

@@ -0,0 +1,127 @@
+import colors     from 'ansi-colors'
+import log        from 'fancy-log'
+import {
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    rmSync,
+    writeFileSync
+}                 from 'fs'
+import {
+    basename,
+    join,
+    relative
+}                 from 'path'
+import { rollup } from 'rollup'
+import {
+    getTaskConfigurationFor,
+    logLoadingTask,
+    packageBuildsDirectory,
+    packageName,
+    packageTestsBundlesDirectory
+}                 from '../../_utils.mjs'
+
+logLoadingTask( import.meta.filename )
+
+const {
+          red,
+          green,
+          magenta,
+      } = colors
+
+const checkBundlingFromEsmBuildImportTask       = async ( done ) => {
+
+    const configuration = await getTaskConfigurationFor( import.meta.filename )
+
+    const buildFilePath = join( packageBuildsDirectory, `${ packageName }.esm.js` )
+    if ( !existsSync( buildFilePath ) ) {
+        done( red( buildFilePath + ' does not exist' ) )
+    }
+
+    const outputDir      = join( packageTestsBundlesDirectory, 'from_build_import' )
+    const temporaryDir   = join( packageTestsBundlesDirectory, 'from_build_import', '.tmp' )
+    const importDir      = relative( temporaryDir, packageBuildsDirectory )
+    const importFilePath = join( importDir, `${ packageName }.esm.js` )
+
+    if ( existsSync( outputDir ) ) {
+        log( 'Clean up', magenta( outputDir ) )
+        rmSync( outputDir, { recursive: true } )
+    }
+
+    try {
+
+        // Get build exports list
+        const data  = readFileSync( buildFilePath, 'utf8' )
+        const regex = /export\s{\s(.*)\s}/
+        const found = data.match( regex )
+        if ( found === null ) {
+            log( red( `Unable to find exports in ${ buildFilePath }` ) )
+            return
+        }
+
+        const exports = found[ 1 ].split( ',' )
+                                  .map( item => item.trim() )
+
+        // Create temporary imports files for each build export
+        // And then bundle it
+        let temporaryFilePaths = []
+        for ( let namedExport of exports ) {
+            if ( namedExport.includes( ' as ' ) ) {
+                namedExport = namedExport.split( ' as ' )[ 1 ]
+            }
+
+            const temporaryFileName = `${ namedExport }.import.js`
+            const temporaryFilePath = join( temporaryDir, temporaryFileName )
+            const temporaryFileData = `import { ${ namedExport } } from '${ importFilePath.replace( /\\/g, '/' ) }'`
+
+            mkdirSync( temporaryDir, { recursive: true } )
+            writeFileSync( temporaryFilePath, temporaryFileData )
+
+            temporaryFilePaths.push( temporaryFilePath )
+        }
+
+        // Bundle each temporary files and check side effects
+        let fileName, bundleFileName, bundleFilePath
+        for ( const temporaryFilePath of temporaryFilePaths ) {
+
+            fileName       = basename( temporaryFilePath )
+            bundleFileName = fileName.replace( '.tmp.', '.bundle.' )
+            bundleFilePath = join( outputDir, bundleFileName )
+
+            try {
+
+                configuration.input       = temporaryFilePath
+                configuration.output.file = bundleFilePath
+
+                const bundle     = await rollup( configuration )
+                const { output } = await bundle.generate( configuration.output )
+
+                let code = output[ 0 ].code
+                if ( code.length > 1 ) {
+                    log( red( `[${ bundleFileName }] contain side-effects !` ) )
+                    await bundle.write( configuration.output )
+                } else {
+                    log( green( `[${ bundleFileName }] is side-effect free.` ) )
+                }
+
+            } catch ( error ) {
+
+                log( red( error.message ) )
+
+            }
+        }
+
+    } catch ( error ) {
+        log( red( error.message ) )
+    } finally {
+
+        done()
+
+    }
+
+}
+checkBundlingFromEsmBuildImportTask.displayName = basename( import.meta.filename, '.task.mjs' )
+checkBundlingFromEsmBuildImportTask.description = 'Verify that the project esm build is correctly importable in third party esm files'
+checkBundlingFromEsmBuildImportTask.flags       = null
+
+export { checkBundlingFromEsmBuildImportTask }