@breadstone-infrastructure/nx-tasks 0.0.257 → 0.0.258

package/readme.md

@@ -0,0 +1,156 @@
+# @breadstone-infrastructure/nx-tasks
+
+A collection of advanced, reusable task executors for [Nx](https://nx.dev/) workspaces, designed to streamline and automate common build, transform, and CI/CD operations across Breadstone projects.
+
+---
+
+## Motivation
+
+The legacy [`tasks`](https://microsoft.github.io/just/) package from Microsoft is no longer maintained and does not support modern Nx or ESM modules. This package provides a robust, extensible alternative, leveraging Nx's executor system for better integration, caching, and developer experience.
+
+---
+
+## Features
+
+- **Reusable Nx Executors**: For build, clean, copy, docs, style, proxy transforms, localization, and more.
+- **Framework Integration**: Supports Angular, React, Vue, Svelte, Lit, and custom elements.
+- **Resource & Localization Tools**: Integrates with [localizator](https://github.com/RueDeRennes/mosaik/tree/main/tools/localizator) for i18n extraction, analysis, and AI-powered translation.
+- **Style Processing**: SCSS/SASS/Lit style transforms, autoprefixing, and bundling.
+- **API & Docs Generation**: OpenAPI codegen, API Extractor, and markdown documentation tools.
+- **Icon Management**: Download and bundle icon collections from remote sources.
+- **CI/CD Friendly**: All tasks are designed for automation and can be used in pipelines.
+- **TypeScript-first**: All code is written in modern TypeScript.
+
+---
+
+## Installation
+
+```sh
+yarn add -D @breadstone-infrastructure/nx-tasks
+# or
+npm install --save-dev @breadstone-infrastructure/nx-tasks
+```
+
+---
+
+## Usage
+
+Add executors to your `project.json` or use them directly via Nx CLI:
+
+```jsonc
+{
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": [
+          "tsc",
+          "nx _build:copy-package"
+        ]
+      }
+    },
+    "release": {
+      "executor": "@breadstone-infrastructure/nx-tasks:release-package"
+    },
+    "localize": {
+      "executor": "@breadstone-infrastructure/nx-tasks:localizator",
+      "options": {
+        "actions": {
+          "analyze": {},
+          "sort": {},
+          "transform": {},
+          "generate": {},
+          "detect": {}
+        },
+      }
+    }
+  }
+}
+```
+
+Or run directly:
+
+```sh
+nx run my-lib:release
+nx run my-lib:localize --mode=analyze
+```
+
+---
+
+## Available Executors
+
+| Executor Name                | Description                                 |
+|------------------------------|---------------------------------------------|
+| `alias-replace`              | Replace aliases and env vars in JS output   |
+| `clean`                      | Clean folders/files                         |
+| `copy`                       | Copy files or directories                   |
+| `docs`                       | Generate markdown docs from templates       |
+| `secrets-config-sync`        | Sync secrets from a provider to .env        |
+| `icon-collection-builder`    | Build icon collections from SVGs            |
+| `icon-collection-downloader` | Download icon sets from remote repos        |
+| `lit-style-transform`        | Transform SCSS to Lit-compatible TS         |
+| `lit-docs`                   | Analyze Lit component docs and JSDoc        |
+| `localizator`                | Extract, analyze, sort, and generate i18n   |
+| `markdown-to-typescript-transform` | Convert markdown to TypeScript modules |
+| `ng-packagr-build`           | Build Angular packages with ng-packagr      |
+| `ng-proxy-transform`         | Generate Angular proxies for web components |
+| `openapi-generator`          | Generate API clients from OpenAPI specs     |
+| `react-proxy-transform`      | Generate React proxies for web components   |
+| `release-package`            | Publish package to npm                      |
+| `release-package-json`       | Prepare/copy package.json for publishing    |
+| `scss-style-bundle`          | Bundle SCSS files                           |
+| `scss-style-transform`       | Transform SCSS to CSS                       |
+| `svelte-proxy-transform`     | Generate Svelte proxies for web components  |
+| `unrelease-package`          | Unpublish package from npm                  |
+| `vercel-edge-config-sync`    | Sync Vercel Edge Config to local app.json   |
+| `vue-proxy-transform`        | Generate Vue proxies for web components     |
+
+See [`executors.json`](./executors.json) for the full list and schema for each executor.
+
+---
+
+## Example: Localization Workflow
+
+```jsonc
+{
+  "targets": {
+    "localize": {
+      "executor": "@breadstone-infrastructure/nx-tasks:localizator",
+      "options": {
+        "mode": "detect",
+        "output": "./locales",
+        "detect": {
+          "preset": "angular",
+          "root": "./src",
+          "type": "json"
+        }
+      }
+    }
+  }
+}
+```
+
+Run with:
+
+```sh
+nx run my-lib:localize --mode=analyze
+nx run my-lib:localize --mode=generate --generate.apiKey=$OPENAI_API_KEY
+```
+
+---
+
+## Development
+
+- Written in TypeScript, using modern ES modules.
+- Uses [@breadstone-infrastructure/utilities](https://github.com/RueDeRennes/mosaik/tree/main/libs/utilities) for file, path, and logging utilities.
+- Each executor is in `src/executors/<name>/`.
+- Add new executors by creating a new folder and updating `executors.json`.
+- Build with `yarn build` or `nx run nx-tasks:build`.
+
+---
+
+## License
+
+MIT © Breadstone
+
+

package/src/_legacy/_Lint.ts

@@ -0,0 +1,40 @@
+
+// #region Imports
+
+import { ConsoleLogger, logSeparator, magenta, Path } from '@breadstone-infrastructure/utilities';
+import { ESLint } from 'eslint';
+
+// #endregion
+
+export namespace LintTask {
+
+    export interface ILintTaskOptions {
+        cwd: string;
+        path: string;
+    }
+
+    export async function run(options: ILintTaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+
+        logSeparator(logger, 'Lint');
+
+        const files = Path.glob(options.path);
+
+        logger.log(magenta(`    linting ${files.length} files.`));
+
+        const eslint = new ESLint({
+            fix: true,
+            cwd: options.cwd
+        });
+
+        const results = await eslint.lintFiles(files);
+        await ESLint.outputFixes(results);
+        const formatter = await eslint.loadFormatter('stylish');
+        const resultText = formatter.format(results, null as unknown as ESLint.LintResultData);
+
+        console.log(resultText);
+
+        logSeparator(logger);
+    }
+
+}

package/src/_legacy/_LitAnalyzer.ts

@@ -0,0 +1,163 @@
+// #region Imports
+
+import { File, Path } from '@breadstone-infrastructure/utilities';
+import { Analyzer } from '@lit-labs/analyzer';
+import * as path from 'path';
+import type { PackageJson, TsConfigJson } from 'type-fest';
+import ts from 'typescript';
+
+// #endregion
+
+export namespace LitAnalyzerTask {
+
+    export const DEFAULT_OPTIONS: Partial<ILitAnalyzerTaskOptions> = {
+        verbose: false
+    };
+
+    export interface ILitAnalyzerTaskOptions {
+        cwd: string;
+        tsConfigJson: TsConfigJson;
+        packageJson: PackageJson;
+        packagePath: string;
+        verbose?: boolean;
+    }
+
+    export async function run(options: ILitAnalyzerTaskOptions): Promise<void> {
+        return new Promise<void>((resolve, reject) => {
+            try {
+                const analyzer = Analysis.createPackageAnalyzer(options.packagePath);
+                const litPackage = analyzer.getPackage();
+                const elementModules = litPackage.getLitElementModules();
+                const { modules } = litPackage;
+
+                const p1 = Path.combine(options.cwd, options.tsConfigJson.compilerOptions?.rootDir ?? '', '_elementModules.json');
+                File.writeAllJson(p1, elementModules);
+                const p2 = Path.combine(options.cwd, options.tsConfigJson.compilerOptions?.rootDir ?? '', '_modules.json');
+                File.writeAllJson(p2, modules);
+
+                console.log('done');
+                resolve();
+            } catch (error) {
+                console.error('Error during analysis:', error);
+                // throw error;
+                reject(error);
+            }
+        });
+    }
+}
+
+namespace Analysis {
+
+    export interface AnalyzerOptions {
+
+        /**
+         * Glob of source files to exclude from project during analysis.
+         *
+         * Useful for excluding things source like test folders that might otherwise
+         * be included in a project's tsconfig.
+         */
+        exclude?: Array<string>;
+    }
+
+    /**
+     * Returns an analyzer for a Lit npm package based on a filesystem path.
+     *
+     * The path may specify a package root folder, or a specific tsconfig file. When
+     * specifying a folder, if no tsconfig.json file is found directly in the root
+     * folder, the project will be analyzed as JavaScript.
+     */
+    export const createPackageAnalyzer = (
+        packagePath: string,
+        options: AnalyzerOptions = {}
+    ): Analyzer => {
+        // This logic accepts either a path to folder containing a tsconfig.json
+        // directly inside it or a path to a specific tsconfig file. If no tsconfig
+        // file is found, we fallback to creating a JavaScript program.
+        const isDirectory = ts.sys.directoryExists(packagePath);
+        const configFileName = isDirectory
+            ? path.join(packagePath, 'tsconfig.json')
+            : packagePath;
+        let commandLine: ts.ParsedCommandLine | null = null;
+        if (ts.sys.fileExists(configFileName)) {
+            // eslint-disable-next-line @typescript-eslint/unbound-method
+            const configFile = ts.readConfigFile(configFileName, ts.sys.readFile);
+            if (options.exclude !== undefined) {
+                (configFile.config.exclude ??= []).push(...options.exclude);
+            }
+            commandLine = ts.parseJsonConfigFileContent(
+                configFile.config /* json */,
+                ts.sys /* host */,
+                isDirectory ? packagePath : path.dirname(packagePath) /* basePath */,
+                {} /* existingOptions */,
+                configFileName /* configFileName */
+            );
+        } else if (isDirectory) {
+            console.info('No tsconfig.json found; assuming package is JavaScript.');
+            commandLine = ts.parseJsonConfigFileContent(
+                {
+                    compilerOptions: {
+                        // TODO(kschaaf): probably want to make this configurable
+                        module: 'es2021',
+                        lib: ['es2021', 'DOM'],
+                        allowJs: true,
+                        skipLibCheck: true,
+                        skipDefaultLibCheck: true,
+                        // With `allowJs: true`, the program will automatically include every
+                        // .d.ts file under node_modules/@types regardless of whether the
+                        // program imported modules associated with those types, which can
+                        // dramatically slow down the program analysis (this does not
+                        // automatically happen when allowJs is false). For now, eliminating
+                        // `typeRoots` fixes the automatic over-inclusion of .d.ts files as
+                        // long as nodeResolution is properly set (it will still import .d.ts
+                        // files into the project as expected based on imports). It may
+                        // however cause a failure to find definitely-typed .d.ts files for
+                        // imports in a JS project, but it seems unlikely these would be
+                        // installed anyway.
+                        typeRoots: [],
+                        moduleResolution: 'node'
+                    },
+                    include: ['**/*.js'],
+                    exclude: options.exclude ?? []
+                },
+                ts.sys /* host */,
+                packagePath /* basePath */
+            );
+        } else {
+            throw new Error(
+                `The specified path '${packagePath}' was not a folder or a tsconfig file.`
+            );
+        }
+
+        // Ensure that `parent` nodes are set in the AST by creating a compiler
+        // host with this configuration; without these, `getText()` and other
+        // API's that require crawling up the AST tree to find the source file
+        // text may fail
+        const compilerHost = ts.createCompilerHost(
+            commandLine.options,
+            /* setParentNodes */ true
+        );
+        const program = ts.createProgram(
+            commandLine.fileNames,
+            commandLine.options,
+            compilerHost,
+            undefined,
+            commandLine.errors
+        );
+
+        const analyzer = new Analyzer({
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            getProgram: () => program,
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            typescript: ts,
+            fs: ts.sys,
+            path
+        });
+        for (const diagnostic of program.getSyntacticDiagnostics()) {
+            analyzer.addDiagnostic(diagnostic);
+        }
+
+        return analyzer;
+    };
+}

package/src/_legacy/_Resources.ts

@@ -0,0 +1,69 @@
+// #region Imports
+
+import { Directory, File, Path, Template, type IFileCacheOptions, ConsoleLogger, logSeparator, gray } from '@breadstone-infrastructure/utilities';
+import { withCaching } from './../utils/withCaching';
+
+// #endregion
+
+export namespace Resources {
+
+    export interface IResourcesTaskOptions {
+        cwd: string;
+        tplFile: string;
+        resourcesPath: string;
+        cache?: IFileCacheOptions;
+    }
+
+    export async function run(options: IResourcesTaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+
+        logSeparator(logger, 'Resources');
+
+        const fileCache = withCaching(options.cache);
+        const tplPath = Path.combine(options.cwd, options.tplFile);
+        const resPath = Path.combine(options.cwd, options.resourcesPath);
+
+        if (!await fileCache.isDirectoryCached(resPath)) {
+            const templateContent = File.readAllText(tplPath);
+            const resFolders = Directory.glob(resPath);
+            const data = new Array<object>();
+
+            for (const resFolder of resFolders) {
+                const name = resFolder.split('/')[resFolder.split('/').length - 1];
+                const group = {
+                    name: name,
+                    files: new Array<object>()
+                };
+
+                logger.log(` ${name}`);
+
+                File.glob(Path.combine(resFolder, '/**/*')).forEach((resFile) => {
+                    const key = Path.getFileNameWithoutExtension(resFile);
+                    const value = resFile;
+
+                    group.files.push({
+                        key: key,
+                        value: Path.relative('src', value)
+                    });
+                    logger.log(`  ${key}`);
+                });
+
+                data.push(group);
+            }
+
+            const fileContent = Template.create({ values: data }, { unescapeContent: true })
+                .apply(templateContent)
+                .toString();
+            File.writeAllText('src/resources/Resources.ts', fileContent);
+
+            if (resFolders.length === 0) {
+                logger.warn('No files found.');
+            }
+        } else {
+            logger.log(gray('\tFile or Folder is up to date.'));
+        }
+
+        logSeparator(logger);
+    }
+
+}

package/src/executors/alias-replace/executor.options.ts

@@ -0,0 +1,10 @@
+// #region Imports
+
+import type { AliasReplaceTask } from './executor.task';
+
+// #endregion
+
+/**
+ * @public
+ */
+export type AliasReplaceExecutorOptions = Omit<AliasReplaceTask.IAliasReplaceTaskOptions, 'cwd' | 'tsConfigJson' | 'packageJson'>;