Pull request #1565: Release/minor 12.1.0

Merge in OUI/oblique from release/minor_12.1.0 to master

* commit 'bd329027b04b39a54ee817d1b2a5b547b8d42124': (50 commits)
  chore(toolchain): release version 12.1.0
  chore(toolchain): update dependencies and refactor accordingly
  feat(cli/update): add `ob update` command
  feat(cli/toolchain): add `update` scope
  feat(cli/toolchain): disable rule of no-console for tests
  fix(oblique/language): remove export of `ObLanguageService`
  refactor(oblique/language): remove deprecation notice of `ObLanguageService`
  feat(sds/focus-with-outline): add focus with outline example
  feat(sandbox/focus-with-outline): add focus sample
  feat(oblique/utilities): add API to focus with outline
  fix(sandbox/notification): add missing translation keys
  fix(oblique/notification): enable dynamic change of translations
  fix(oblique/service-navigation): make language dropdown keyboard accessible
  fix(service-navigation/web-component): show focus on language dropdown
  feat(oblique/language): remove `DateAdapter` warning
  feat(sandbox/master-layout): show parent main menu item without URL
  refactor(sandbox/master-layout): move navigation to a dedicated file
  feat(oblique/master-layout): add support for parent main menu item without URL
  feat(oblique/material): deprecate `ObSelectDirective`
  feat(oblique/material): deprecate `ObFormFieldModule`
  ...

Jenkinsfile

@@ -42,6 +42,7 @@ nodejsPipelineTemplate {
 		master: [
 			'publish': [
 				'./dist/oblique',
+				'./dist/cli',
 				'./dist/service-navigation-web-component'
 			],
 			'gitTag': true,

package.json

@@ -1,7 +1,7 @@
 {
   "title": "Oblique",
   "name": "oblique",
-  "version": "12.0.4",
+  "version": "12.1.0",
   "license": "MIT",
   "organization": {
     "name": "Federal Office of Information Technology, Systems and Telecommunication FOITT",
@@ -70,7 +70,7 @@
     "@angular-devkit/core": "^18.2.4",
     "@angular-eslint/eslint-plugin": "^18.3.1",
     "@angular-eslint/eslint-plugin-template": "^18.3.1",
-    "@angular-eslint/template-parser": "^18.4.2",
+    "@angular-eslint/template-parser": "^18.4.3",
     "@angular/cli": "^18.2.12",
     "@angular/compiler-cli": "^18.2.13",
     "@types/jest": "^29.5.14",
@@ -85,7 +85,7 @@
     "jest": "^29.7.0",
     "jest-sonar": "^0.2.16",
     "lint-staged": "^15.2.10",
-    "prettier": "^3.4.1",
+    "prettier": "^3.4.2",
     "stylelint": "^16.11.0",
     "stylelint-config-prettier-scss": "^1.0.0",
     "stylelint-config-standard-scss": "^13.1.0",

projects/cli/.eslintrc.yml

@@ -16,3 +16,18 @@ overrides:
             - error
             - time
             - timeEnd
+      "@typescript-eslint/no-magic-numbers":
+        - error
+        - ignore:
+            - -1
+            - 0
+            - 1
+  - files:
+      - "*.spec.ts"
+    parserOptions:
+      project:
+        - projects/cli/tsconfig.spec.json
+    rules:
+      "no-console": "off"
+      "@typescript-eslint/no-magic-numbers": "off"
+      "@typescript-eslint/no-unsafe-assignment": "off"

projects/cli/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [12.1.0](https://github.com/oblique-bit/oblique/compare/12.0.4...12.1.0) (2024-12-09)
+
+## Features
+
+- **new:** add `ob new` command ([b2ddd17b](https://github.com/oblique-bit/oblique/commit/b2ddd17bfa701c01058298e39b74862b4424d6e7))
+- **update:** add `ob update` command ([e1ec0fdc](https://github.com/oblique-bit/oblique/commit/e1ec0fdc2b716c905e94e10eb1cf1b03c7350d6d))
+
 # [12.0.0](https://github.com/oblique-bit/oblique/compare/11.3.4...12.0.0) (2024-10-08)
 
 ## Features

projects/cli/CONTRIBUTING.md

@@ -7,3 +7,6 @@ All commits related to the CLI package must use the **cli** package and 1 of the
 ## <a name="scope"></a> Scope
 
 - **toolchain**
+- **utils**
+- **new**
+- **update**

projects/cli/README.md

@@ -14,6 +14,7 @@ You will find information about how to use Oblique, its CLI, code samples, FAQ a
 
 ## Scripts
 
+- **link**: builds the CLI and call `npm link` on the artifact to allow the CLI to be called globally
 - **lint**: lints the project with EsLint and Prettier; Automatically run on the CI pipeline
 - **format**: same as lint, but with autofix parameter
 - **test**: run all tests and collects coverage

projects/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oblique/cli",
-  "version": "12.0.4",
+  "version": "12.1.0",
   "description": "Command Line Interface to manage Oblique projects",
   "keywords": [
     "ob",
@@ -13,6 +13,7 @@
   },
   "scripts": {
     "start": "ts-node src/index.ts",
+    "link": "npm uninstall @oblique/cli -g && npm run build && cd ../../dist/cli && npm link",
     "lint": "ts-node scripts/lint.ts",
     "format": "npm run lint -- --fix",
     "test": "jest",
@@ -21,6 +22,7 @@
     "release": "ts-node scripts/release.ts"
   },
   "dependencies": {
-    "@commander-js/extra-typings": "^12.1.0"
+    "@commander-js/extra-typings": "^12.1.0",
+    "chalk": "^4.1.2"
   }
 }

projects/cli/sonar-project.properties

@@ -1,6 +1,6 @@
 sonar.projectName=@oblique/cli
 sonar.projectKey=oblique_cli
-sonar.projectVersion=12.0.4
+sonar.projectVersion=12.1.0
 sonar.typescript.lcov.reportPaths=coverage/cli/lcov.info
 sonar.testExecutionReportPaths=coverage/cli/sqr.xml
 sonar.tests=projects/cli/src

projects/cli/src/index.spec.ts

@@ -1,9 +1,9 @@
-import {SpawnSyncOptions, spawnSync} from 'child_process';
-import * as path from 'path';
-import * as packageFile from './../package.json';
+import {SpawnSyncOptions, spawnSync} from 'node:child_process';
+import path from 'path';
+import * as cliPackage from '../package.json';
 
-describe('Oblique CLI', () => {
-	let cliPath: string;
+describe('index.ts', () => {
+	const cliPath = path.resolve(__dirname, './index.ts');
 	const workingDirectory = path.resolve(__dirname, '../../../../');
 	const options = {
 		encoding: 'utf-8',
@@ -12,58 +12,56 @@ describe('Oblique CLI', () => {
 		cwd: workingDirectory
 	} as SpawnSyncOptions;
 
-	beforeAll(() => {
-		cliPath = path.resolve(__dirname, './index.ts');
-	});
+	describe('Oblique CLI with spawnSync', () => {
+		describe.each(['-h', '--help'])('help option with %s', flag => {
+			test(`stdout should not be empty`, () => {
+				const result = spawnSync('ts-node', [cliPath, flag], options);
+				expect(result.stdout).not.toBe('');
+			});
 
-	describe.each(['-h', '--help'])('help option with %s', flag => {
-		test(`stdout should not be empty`, () => {
-			const result = spawnSync('ts-node', [cliPath, flag], options);
-			expect(result.stdout).not.toBe('');
+			test(`stderr should be empty`, () => {
+				const result = spawnSync('ts-node', [cliPath, flag], options);
+				expect(result.stderr).toBe('');
+			});
 		});
 
-		test(`stderr should be empty`, () => {
-			const result = spawnSync('ts-node', [cliPath, flag], options);
-			expect(result.stderr).toBe('');
-		});
-	});
+		describe.each(['-v', '--version'])('version option with %s', flag => {
+			test(`stdout should contain the version from package.json`, () => {
+				const result = spawnSync('ts-node', [cliPath, flag]);
+				expect(cleanOutput(result.stdout)).toBe(cleanOutput(cliPackage.version));
+			});
 
-	describe.each(['-v', '--version'])('version option with %s', flag => {
-		test(`stdout should contain the version from package.json`, () => {
-			const result = spawnSync('ts-node', [cliPath, flag], options);
-			expect(cleanOutput(result.stdout.toString())).toBe(cleanOutput(packageFile.version));
+			test(`stderr should be empty`, () => {
+				const result = spawnSync('ts-node', [cliPath, flag], options);
+				expect(result.stderr).toBe('');
+			});
 		});
 
-		test(`stderr should be empty`, () => {
-			const result = spawnSync('ts-node', [cliPath, flag], options);
-			expect(result.stderr).toBe('');
-		});
-	});
+		describe.each([
+			{correctOption: '--help', wrongOption: '--holp'},
+			{correctOption: '--version', wrongOption: '--vorsion'}
+		])(`Wrong Option $wrongOption instead of $correctOption`, ({wrongOption, correctOption}) => {
+			test(`show suggestion "(Did you mean ${correctOption}?)"`, () => {
+				const result = spawnSync('ts-node', [cliPath, wrongOption], options);
+				expect(cleanOutput(result.stderr.toString())).toContain(`(Did you mean ${correctOption}?)`);
+			});
 
-	describe.each([
-		{correctOption: '--help', wrongOption: '--holp'},
-		{correctOption: '--version', wrongOption: '--vorsion'}
-	])(`Wrong Option $wrongOption instead of $correctOption`, ({wrongOption, correctOption}) => {
-		test(`show suggestion "(Did you mean ${correctOption}?)"`, () => {
-			const result = spawnSync('ts-node', [cliPath, wrongOption], options);
-			expect(cleanOutput(result.stderr.toString())).toContain(`(Did you mean ${correctOption}?)`);
+			test(`stdout should be empty`, () => {
+				const result = spawnSync('ts-node', [cliPath, wrongOption], options);
+				expect(result.stdout).toBe('');
+			});
 		});
 
-		test(`stdout should be empty`, () => {
-			const result = spawnSync('ts-node', [cliPath, wrongOption], options);
-			expect(result.stdout).toBe('');
-		});
-	});
-
-	describe('error handling for unknown options', () => {
-		test(`stderr should contain "error: unknown option '--unicornpoop'"`, () => {
-			const result = spawnSync('ts-node', [cliPath, '--unicornpoop'], options);
-			expect(cleanOutput(result.stderr)).toContain(`error: unknown option '--unicornpoop'`);
-		});
+		describe('error handling for unknown options', () => {
+			test(`stderr should contain "error: unknown option '--unicornpoop'"`, () => {
+				const result = spawnSync('ts-node', [cliPath, '--unicornpoop'], options);
+				expect(cleanOutput(result.stderr)).toContain(`error: unknown option '--unicornpoop'`);
+			});
 
-		test(`stdout should be empty for unknown option`, () => {
-			const result = spawnSync('ts-node', [cliPath, '--unicornpoop'], options);
-			expect(result.stdout).toBe('');
+			test(`stdout should be empty for unknown option`, () => {
+				const result = spawnSync('ts-node', [cliPath, '--unicornpoop'], options);
+				expect(result.stdout).toBe('');
+			});
 		});
 	});
 

projects/cli/src/index.ts

@@ -2,28 +2,43 @@
 
 import {program} from '@commander-js/extra-typings';
 import * as cliPackage from '../package.json';
-import {exampleUsageText, obTitle, obUsageText, optionDescriptions, runObCommand, startObCommand, titleText} from './utils/cli-utils';
+import {createObNewCommand} from './new/ob-new';
+import {
+	commandUsageText,
+	createAdditionalHelpText,
+	obExamples,
+	obTitle,
+	optionDescriptions,
+	runObCommand,
+	startObCommand,
+	titleText
+} from './utils/cli-utils';
+import {createObUpdateCommand} from './update/ob-update';
 
 program
 	.name('ob')
 	.description(cliPackage.description)
-	.version(cliPackage.version, optionDescriptions.version.flags, optionDescriptions.version.description)
-	.helpOption(optionDescriptions.help.flags, optionDescriptions.help.description)
-	.usage(obUsageText)
+	.version(cliPackage.version, optionDescriptions.ob.version.flags, optionDescriptions.ob.version.description)
+	.helpOption(optionDescriptions.ob.help.flags, optionDescriptions.ob.help.description)
+	.usage(commandUsageText('<command>'))
 	.addHelpText('beforeAll', titleText(`How to use the ${obTitle}`.toUpperCase(), ''))
-	.addHelpText(
-		'after',
-		exampleUsageText([
-			{command: optionDescriptions.version.command, description: optionDescriptions.version.description},
-			{command: optionDescriptions.help.command, description: optionDescriptions.help.description}
-		])
-	)
+	.addHelpText('after', createAdditionalHelpText('\nExample usages:\n', obExamples, getMaxCommandLength(obExamples)))
 	.action(handleAction)
 	.showSuggestionAfterError(true)
-	.showHelpAfterError(true);
+	.showHelpAfterError('(Add --help for additional information)');
+
+const obNewCommandConfigured = createObNewCommand();
+const obUpdateCommandConfigured = createObUpdateCommand();
+
+program.addCommand(obNewCommandConfigured);
+program.addCommand(obUpdateCommandConfigured);
 
 program.parse();
 
-function handleAction(options: Record<string, string>): void {
-	startObCommand(options, runObCommand, 'Oblique CLI completed in');
+export function handleAction(options: Record<string, string>): void {
+	startObCommand(runObCommand, 'Oblique CLI completed in', options);
+}
+
+export function getMaxCommandLength(examples: {command: string; description: string}[]): number {
+	return examples.map(entry => entry.command.length).reduce((max, length) => (length > max ? length : max), 0);
 }

projects/cli/src/new/ob-new.model.ts

@@ -0,0 +1,67 @@
+import {Command, OptionValues} from '@commander-js/extra-typings';
+import {getVersionedDependency, projectNamePlaceholder} from '../utils/cli-utils';
+
+export type ObNewOptions<ValueType> = Record<OptionKeys, ValueType>;
+
+export interface ObNewSchemaOption {
+	type: string;
+	description: string;
+	shortFlag?: string;
+	defaultValue?: boolean | string;
+	flagValuePlaceholder?: string;
+	defaultValueDescription?: string;
+	choices?: string[];
+	mandatory?: boolean;
+	resources?: string[];
+}
+
+export interface HandleObNewActionOptions {
+	projectName: string;
+	command: Command<[string], OptionValues>;
+}
+
+export type OptionKeys =
+	| 'title'
+	| 'locales'
+	| 'ajv'
+	| 'unknownRoute'
+	| 'httpInterceptors'
+	| 'banner'
+	| 'environments'
+	| 'externalLink'
+	| 'prefix'
+	| 'jest'
+	| 'protractor'
+	| 'npmrc'
+	| 'proxy'
+	| 'sonar'
+	| 'eslint'
+	| 'husky';
+
+export type ImmutableOptionsType = 'no-standalone' | 'no-ssr' | 'style';
+
+export const immutableOptions: Record<ImmutableOptionsType, {value?: string; description: string}> = {
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	'no-standalone': {
+		description: `Oblique doesn't support standalone components`
+	},
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	'no-ssr': {
+		description: `Oblique doesn't support server side rendering`
+	},
+	style: {
+		value: 'scss',
+		description: 'Oblique uses SCSS'
+	}
+};
+
+export const obNewConfig = {
+	obNewSummaryText: `Creates an Oblique project`,
+	projectNameArgument: {
+		description: `Unique name for your new project`,
+		argumentName: projectNamePlaceholder
+	}
+};
+
+export const createsWorkspaceMessage = `\nCreates a new Angular workspace`;
+export const ngAddStringCommand = `npx ${getVersionedDependency('@angular/cli')} add ${getVersionedDependency('@oblique/oblique')}`;