@3ddv/software-division-components 1.4.1 → 1.4.2

package/docs/releasing.md

@@ -0,0 +1,306 @@
+[BACK TO THE TOP](../README.md)
+
+# Software Division Components (SDC) - Release Guide
+
+This guide explains how to release a new version of the Software Division Components library to npm.
+
+## Prerequisites
+
+- **Clean working tree**: All changes must be committed before releasing
+- **npm authentication**: You must be authenticated with npm and have publish permissions
+- **Git access**: You must have push access to the repository
+- **Current version**: Verify the current published version on npm matches your local Lerna version
+
+## Pre-Release Checklist
+
+Before starting the release process, ensure:
+
+1. **All changes are committed and pushed**:
+   ```bash
+   git status  # Should show "nothing to commit, working tree clean"
+   git push origin <your-branch-name>
+   ```
+
+2. **You're on the correct branch** (typically `master` or `main`):
+   ```bash
+   git checkout master
+   git pull origin master
+   ```
+
+3. **Verify npm authentication**:
+   ```bash
+   npm whoami  # Should show your npm username
+   ```
+
+4. **Check current versions**:
+   ```bash
+   # Check published version on npm
+   npm view @3ddv/software-division-components version
+
+   # Check local Lerna version
+   cat lerna.json | grep version
+   ```
+
+## Release Process
+
+### Step 1: Sync Version (If Needed)
+
+If your local Lerna version doesn't match the published npm version, sync them first:
+
+```bash
+# Update lerna.json to match npm version
+# Edit lerna.json: "version": "1.0.5" (example)
+
+# Commit the sync
+git add lerna.json
+git commit -m "chore: sync lerna version to 1.0.5"
+```
+
+### Step 2: Bump Version
+
+Use Lerna to bump the version. Choose the appropriate version type:
+
+- **Patch** (`1.0.5` → `1.0.6`): Bug fixes
+- **Minor** (`1.0.5` → `1.1.0`): New features, non-breaking changes
+- **Major** (`1.0.5` → `2.0.0`): Breaking changes
+
+**Option A: Direct version bump** (recommended):
+```bash
+npx lerna version minor --yes
+# Or: npx lerna version patch --yes
+# Or: npx lerna version major --yes
+```
+
+**Option B: Interactive mode**:
+```bash
+pnpm run version
+# Select the version type when prompted
+```
+
+**What this does:**
+- Runs the `preversion` hook: checks for changed packages, builds the library, changes to `dist/`
+- Updates versions in `lerna.json` and `projects/software-division-components/package.json`
+- Creates a git commit with the version bump
+- Creates a git tag (e.g., `v1.1.0`)
+
+### Step 3: Verify Version Update
+
+Check that versions were updated correctly:
+
+```bash
+cat lerna.json | grep version
+cat projects/software-division-components/package.json | grep version
+git log --oneline -1  # Should show the version commit
+git tag | grep v1.1.0  # Should show the new tag
+```
+
+### Step 4: Build the Library
+
+The `preversion` hook should have built the library, but verify:
+
+```bash
+pnpm run build
+```
+
+This runs:
+- `clean` - removes old dist folder
+- `generate-versions` - updates version badges in README
+- `compile:lib` - builds Angular library
+- `compile:lib:styles` - compiles Tailwind styles
+- `after:build` - copies README to dist
+
+### Step 5: Verify Dist Folder
+
+Ensure the `dist` folder contains the built package with the correct version:
+
+```bash
+ls -la dist/
+cat dist/package.json | grep version  # Should show the new version
+```
+
+### Step 6: Publish to npm
+
+**Important**: Use `from-package` mode to publish an already-versioned package:
+
+```bash
+npx lerna publish from-package --yes
+```
+
+**Why `from-package`?**
+- The `prepublish` hook checks for changed packages using `lerna changed`
+- After versioning, Lerna may not detect changes because the version was already committed
+- `from-package` publishes packages that have a version in `package.json` that doesn't exist in the npm registry
+
+**What this does:**
+- Runs the `prepublish` hook: checks for changed packages, builds, changes to `dist/`
+- Publishes from the `dist` directory (configured in `publishConfig.directory`)
+- Publishes to npm registry as `@3ddv/software-division-components@<version>`
+
+### Step 7: Push Tags and Commits
+
+After successful publish, push the version commit and tag:
+
+```bash
+git push origin <your-branch-name>
+git push origin --tags
+```
+
+## Post-Release Verification
+
+1. **Verify on npm**:
+   ```bash
+   npm view @3ddv/software-division-components version
+   ```
+
+2. **Verify git tag**:
+   ```bash
+   git tag | grep v1.1.0
+   ```
+
+3. **Test installation** (optional):
+   ```bash
+   npm install @3ddv/software-division-components@1.1.0
+   ```
+
+## Troubleshooting
+
+### Error: "Working tree has uncommitted changes"
+
+**Problem**: Lerna requires a clean working tree before versioning.
+
+**Solution**:
+```bash
+# Check what's uncommitted
+git status
+
+# Commit or discard changes
+git add .
+git commit -m "chore: prepare for release"
+# OR
+git checkout <file>  # to discard changes
+```
+
+### Error: "tag 'v1.1.0' already exists"
+
+**Problem**: The git tag already exists locally or remotely.
+
+**Solution**:
+```bash
+# Check if tag exists locally
+git tag | grep v1.1.0
+
+# If it exists locally but shouldn't, delete it
+git tag -d v1.1.0
+
+# If it exists remotely, check if version was already published
+npm view @3ddv/software-division-components version
+```
+
+### Error: "No changed packages found" during publish
+
+**Problem**: The `prepublish` hook checks for changed packages, but after versioning, Lerna may not detect changes.
+
+**Solution**: Use `from-package` mode:
+```bash
+npx lerna publish from-package --yes
+```
+
+### Error: "npm authentication failed"
+
+**Problem**: You're not authenticated with npm or don't have publish permissions.
+
+**Solution**:
+```bash
+# Check authentication
+npm whoami
+
+# Login if needed
+npm login
+
+# Verify you have access to the package
+npm access ls-packages
+```
+
+### Version Mismatch Between Lerna and npm
+
+**Problem**: Local Lerna version doesn't match published npm version.
+
+**Solution**:
+1. Check both versions:
+   ```bash
+   npm view @3ddv/software-division-components version
+   cat lerna.json | grep version
+   ```
+
+2. Update `lerna.json` to match npm version:
+   ```bash
+   # Edit lerna.json to match npm version
+   git add lerna.json
+   git commit -m "chore: sync lerna version to <version>"
+   ```
+
+## Version Bump Guidelines
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (`1.0.0` → `2.0.0`): Breaking changes
+  - API changes that break backward compatibility
+  - Removing features
+  - Changing component APIs in incompatible ways
+
+- **MINOR** (`1.0.0` → `1.1.0`): New features, backward compatible
+  - Adding new components
+  - Adding new features to existing components
+  - Non-breaking API additions
+
+- **PATCH** (`1.0.0` → `1.0.1`): Bug fixes, backward compatible
+  - Bug fixes
+  - Performance improvements
+  - Documentation updates
+
+## Quick Reference
+
+### Complete Release Workflow
+
+```bash
+# 1. Ensure clean working tree
+git status
+git push origin <branch>
+
+# 2. Sync version if needed
+# Edit lerna.json if version mismatch exists
+git add lerna.json
+git commit -m "chore: sync lerna version to X.X.X"
+
+# 3. Bump version
+npx lerna version minor --yes  # or patch/major
+
+# 4. Verify build
+pnpm run build
+cat dist/package.json | grep version
+
+# 5. Publish
+npx lerna publish from-package --yes
+
+# 6. Push tags
+git push origin <branch>
+git push origin --tags
+
+# 7. Verify
+npm view @3ddv/software-division-components version
+```
+
+## Important Notes
+
+1. **Never manually edit version numbers**: Always use Lerna commands to manage versions
+2. **Always use `from-package` for publishing**: This avoids issues with the `prepublish` hook
+3. **Test before releasing**: Ensure the library builds and works correctly
+4. **Follow conventional commits**: Commit messages should follow the Conventional Commits format
+5. **Document breaking changes**: If releasing a major version, document all breaking changes
+
+## Related Documentation
+
+- [Semantic Versioning](https://semver.org/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Lerna Documentation](https://lerna.js.org/)
+

package/eslint.config.ts

@@ -0,0 +1,209 @@
+import { Linter } from 'eslint';
+import jsdoc from 'eslint-plugin-jsdoc';
+import prettier from 'eslint-plugin-prettier';
+
+const config: Linter.Config = {
+  ignores: ['node_modules', 'dist', 'build', '.eslintrc.js', '*.js', '*.json', '.vscode'],
+  plugins: { prettier, jsdoc },
+  rules: {
+    '@typescript-eslint/adjacent-overload-signatures': 'error',
+    '@typescript-eslint/array-type': 'error',
+    '@typescript-eslint/await-thenable': 'error',
+    '@typescript-eslint/ban-ts-comment': 'error',
+    '@typescript-eslint/ban-tslint-comment': 'error',
+    '@typescript-eslint/ban-types': 'error',
+    '@typescript-eslint/class-literal-property-style': 'error',
+    '@typescript-eslint/consistent-indexed-object-style': 'off',
+    '@typescript-eslint/consistent-type-assertions': 'error',
+    '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
+    '@typescript-eslint/consistent-type-imports': 'error',
+    '@typescript-eslint/consistent-type-exports': 'error',
+    '@typescript-eslint/explicit-function-return-type': 'error',
+    '@typescript-eslint/explicit-member-accessibility': 'error',
+    '@typescript-eslint/explicit-module-boundary-types': 'error',
+    '@typescript-eslint/method-signature-style': 'off',
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        selector: 'default',
+        format: ['camelCase'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'import',
+        format: ['camelCase', 'PascalCase'],
+      },
+      {
+        selector: 'variable',
+        format: ['camelCase'],
+        types: ['function'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'variable',
+        format: ['snake_case', 'UPPER_CASE'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'parameter',
+        format: ['camelCase'],
+        types: ['function'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'parameter',
+        format: ['snake_case'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'classProperty',
+        format: ['camelCase'],
+        types: ['function'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'classProperty',
+        format: ['snake_case'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'classMethod',
+        format: ['camelCase'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'class',
+        format: ['PascalCase'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'objectLiteralProperty',
+        format: ['snake_case', 'camelCase', 'UPPER_CASE'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'typeProperty',
+        format: ['snake_case', 'camelCase', 'UPPER_CASE'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'accessor',
+        format: ['snake_case'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'accessor',
+        format: ['camelCase'],
+        types: ['function'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+      {
+        selector: 'typeLike',
+        format: ['PascalCase'],
+      },
+      {
+        selector: 'enumMember',
+        format: ['PascalCase', 'camelCase', 'snake_case', 'UPPER_CASE'],
+      },
+      {
+        selector: 'memberLike',
+        format: ['camelCase', 'snake_case'],
+        leadingUnderscore: 'allowSingleOrDouble',
+      },
+    ],
+    '@typescript-eslint/no-base-to-string': 'error',
+    '@typescript-eslint/no-confusing-non-null-assertion': 'error',
+    '@typescript-eslint/no-confusing-void-expression': ['error', { ignoreArrowShorthand: true }],
+    '@typescript-eslint/no-dynamic-delete': 'error',
+    '@typescript-eslint/no-empty-interface': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-extra-non-null-assertion': 'error',
+    '@typescript-eslint/no-extraneous-class': 'error',
+    '@typescript-eslint/no-floating-promises': 'error',
+    '@typescript-eslint/no-for-in-array': 'error',
+    '@typescript-eslint/no-inferrable-types': 'off',
+    '@typescript-eslint/no-invalid-void-type': 'error',
+    '@typescript-eslint/no-misused-new': 'error',
+    '@typescript-eslint/no-misused-promises': 'error',
+    '@typescript-eslint/no-namespace': 'error',
+    '@typescript-eslint/no-non-null-asserted-optional-chain': 'error',
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/no-require-imports': 'error',
+    '@typescript-eslint/no-this-alias': 'error',
+    '@typescript-eslint/no-type-alias': [
+      'off',
+      { allowCallbacks: 'always', allowAliases: 'always', allowTupleTypes: 'always', allowConstructors: true },
+    ],
+    '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'error',
+    '@typescript-eslint/no-unnecessary-condition': ['off', { allowConstantLoopConditions: true }],
+    '@typescript-eslint/no-unnecessary-qualifier': 'error',
+    '@typescript-eslint/no-unnecessary-type-arguments': 'error',
+    '@typescript-eslint/no-unnecessary-type-assertion': 'error',
+    '@typescript-eslint/no-unnecessary-type-constraint': 'error',
+    '@typescript-eslint/no-unsafe-assignment': 'error',
+    '@typescript-eslint/no-unsafe-call': 'error',
+    '@typescript-eslint/no-unsafe-member-access': 'off',
+    '@typescript-eslint/no-unsafe-return': 'error',
+    '@typescript-eslint/no-var-requires': 'error',
+    '@typescript-eslint/non-nullable-type-assertion-style': 'error',
+    '@typescript-eslint/prefer-as-const': 'error',
+    '@typescript-eslint/prefer-enum-initializers': 'error',
+    '@typescript-eslint/prefer-for-of': 'off',
+    '@typescript-eslint/prefer-function-type': 'error',
+    '@typescript-eslint/prefer-includes': 'off',
+    '@typescript-eslint/prefer-literal-enum-member': 'error',
+    '@typescript-eslint/prefer-namespace-keyword': 'error',
+    '@typescript-eslint/prefer-nullish-coalescing': 'error',
+    '@typescript-eslint/prefer-optional-chain': 'error',
+    '@typescript-eslint/prefer-readonly': 'error',
+    '@typescript-eslint/prefer-readonly-parameter-types': 'off',
+    '@typescript-eslint/prefer-reduce-type-parameter': 'error',
+    '@typescript-eslint/prefer-regexp-exec': 'error',
+    '@typescript-eslint/prefer-string-starts-ends-with': 'error',
+    '@typescript-eslint/prefer-ts-expect-error': 'off',
+    '@typescript-eslint/promise-function-async': 'off',
+    '@typescript-eslint/require-array-sort-compare': 'error',
+    '@typescript-eslint/restrict-plus-operands': 'error',
+    '@typescript-eslint/restrict-template-expressions': ['error', { allowBoolean: true }],
+    '@typescript-eslint/strict-boolean-expressions': [
+      'off',
+      { allowString: true, allowNullableObject: true, allowNullableBoolean: false },
+    ],
+    '@typescript-eslint/switch-exhaustiveness-check': 'error',
+    '@typescript-eslint/triple-slash-reference': ['error', {}],
+    '@typescript-eslint/typedef': 'error',
+    '@typescript-eslint/unbound-method': 'error',
+    '@typescript-eslint/unified-signatures': 'error',
+    '@typescript-eslint/default-param-last': 'error',
+    '@typescript-eslint/dot-notation': 'error',
+    '@typescript-eslint/init-declarations': 'off',
+    '@typescript-eslint/lines-between-class-members': 'off',
+    '@typescript-eslint/no-array-constructor': 'error',
+    '@typescript-eslint/no-dupe-class-members': 'error',
+    '@typescript-eslint/no-empty-function': 'error',
+    '@typescript-eslint/no-implied-eval': 'error',
+    '@typescript-eslint/no-invalid-this': 'error',
+    '@typescript-eslint/no-loop-func': 'error',
+    '@typescript-eslint/no-loss-of-precision': 'error',
+    '@typescript-eslint/no-magic-numbers': 'off',
+    '@typescript-eslint/no-redeclare': 'error',
+    '@typescript-eslint/no-shadow': 'error',
+    '@typescript-eslint/no-throw-literal': 'error',
+    '@typescript-eslint/no-unused-expressions': ['error', { allowTernary: true }],
+    '@typescript-eslint/no-unused-vars': ['off', { args: 'none', vars: 'local' }],
+    '@typescript-eslint/no-use-before-define': ['error', { functions: false }],
+    '@typescript-eslint/no-useless-constructor': 'error',
+    '@typescript-eslint/require-await': 'error',
+    '@typescript-eslint/return-await': 'error',
+    '@typescript-eslint/no-unsafe-declaration-merging': 'off',
+    'import/export': 'off',
+    'import/consistent-type-specifier-style': 'error',
+    'import/no-duplicates': 'error',
+    'eqeqeq': ['error', 'smart'],
+    'no-bitwise': 'off',
+    'no-prototype-builtins': 'off',
+    'no-unused-vars': 'off',
+  },
+};
+
+export default config;

package/lerna-debug.log

@@ -0,0 +1,71 @@
+0 silly argv {
+0 silly argv   _: [ 'publish' ],
+0 silly argv   composed: 'publish',
+0 silly argv   lernaVersion: '8.2.3',
+0 silly argv   '$0': 'node_modules/lerna/dist/cli.js'
+0 silly argv }
+1 notice cli v8.2.3
+2 verbose packageConfigs Explicit "packages" configuration found in lerna.json. Resolving packages using the configured glob(s): ["projects/software-division-components"]
+3 verbose rootPath /home/vikms/Desktop/First party libraries/SDC/ticketing-598-software-division-components-npm
+4 verbose session c5025ca5d07e20df
+5 verbose user-agent lerna/8.2.3/node@v22.11.0+x64 (linux)
+6 info publish rooted leaf detected, skipping synthetic root lifecycles
+7 verbose silly Interpolated string "./dist" for node "@3ddv/software-division-components" to produce "./dist"
+8 silly argv { _: [ 'publish' ], composed: 'publish', lernaVersion: '8.2.3' }
+9 verbose packageConfigs Explicit "packages" configuration found in lerna.json. Resolving packages using the configured glob(s): ["projects/software-division-components"]
+10 verbose rootPath /home/vikms/Desktop/First party libraries/SDC/ticketing-598-software-division-components-npm
+11 info current version 1.0.0
+12 silly isAnythingCommitted
+13 verbose isAnythingCommitted 1
+14 silly getCurrentBranch
+15 verbose currentBranch master
+16 silly remoteBranchExists
+17 silly isBehindUpstream
+18 silly isBehindUpstream master is behind origin/master by 0 commit(s) and ahead by 0
+19 silly hasTags
+20 verbose hasTags true
+21 silly git-describe.sync "v1.0.0-3-g5ea5c1b" => {"lastTagName":"v1.0.0","lastVersion":"v1.0.0","refCount":"3","sha":"5ea5c1b","isDirty":false}
+22 info Looking for changed packages since v1.0.0
+23 silly checking diff projects/software-division-components
+24 silly found diff in projects/software-division-components/package.json
+24 silly found diff in projects/software-division-components/src/dvm/neighbors/neighbors.component.ts
+25 verbose filtered diff [
+25 verbose filtered diff   'projects/software-division-components/package.json',
+25 verbose filtered diff   'projects/software-division-components/src/dvm/neighbors/neighbors.component.ts'
+25 verbose filtered diff ]
+26 verbose updated @3ddv/software-division-components
+27 verbose git-describe undefined => "v1.0.0-3-g5ea5c1b"
+28 silly git-describe parsed => {"lastTagName":"v1.0.0","lastVersion":"v1.0.0","refCount":"3","sha":"5ea5c1b","isDirty":false}
+29 info execute Skipping releases
+30 silly lifecycle No script for "preversion" in "@3ddv/software-division-components", continuing
+31 verbose version @3ddv/software-division-components has no lockfile. Skipping lockfile update.
+32 silly lifecycle No script for "version" in "@3ddv/software-division-components", continuing
+33 verbose version Updating root pnpm-lock.yaml
+34 silly version Successfully applied prettier to updated file: projects/software-division-components/package.json
+35 silly version Successfully applied prettier to updated file: lerna.json
+36 silly version Successfully applied prettier to updated file: pnpm-lock.yaml
+37 silly gitAdd [
+37 silly gitAdd   'projects/software-division-components/package.json',
+37 silly gitAdd   'lerna.json',
+37 silly gitAdd   'pnpm-lock.yaml'
+37 silly gitAdd ]
+38 silly gitCommit v1.0.1
+39 verbose git [ 'commit', '-m', 'v1.0.1' ]
+40 silly gitTag v1.0.1 git tag %s -m %s
+41 verbose git [ 'tag', 'v1.0.1', '-m', 'v1.0.1' ]
+42 silly lifecycle No script for "postversion" in "@3ddv/software-division-components", continuing
+43 info git Pushing tags...
+44 silly gitPush origin master
+45 info publish Publishing packages to npm...
+46 silly getCurrentSHA
+47 verbose getCurrentSHA 29b5d70610080690e9930a03af258b662bf8caec
+48 verbose pack-directory projects/software-division-components/dist
+49 silly lifecycle No script for "prepublish" in "@3ddv/software-division-components", continuing
+50 silly lifecycle No script for "prepare" in "@3ddv/software-division-components", continuing
+51 silly lifecycle No script for "prepublishOnly" in "@3ddv/software-division-components", continuing
+52 silly lifecycle No script for "prepack" in "@3ddv/software-division-components", continuing
+53 error Error: ENOENT: no such file or directory, lstat '/home/vikms/Desktop/First party libraries/SDC/ticketing-598-software-division-components-npm/projects/software-division-components/dist'
+53 error     at async lstat (node:internal/fs/promises:1023:18)
+53 error     at async #loadActual (/home/vikms/Desktop/First party libraries/SDC/ticketing-598-software-division-components-npm/node_modules/.pnpm/@npmcli+arborist@7.5.4/node_modules/@npmcli/arborist/lib/arborist/load-actual.js:129:15)
+53 error     at async packDirectory (/home/vikms/Desktop/First party libraries/SDC/ticketing-598-software-division-components-npm/node_modules/.pnpm/lerna@8.2.3_@types+node@24.3.1_babel-plugin-macros@3.1.0_encoding@0.1.13/node_modules/lerna/dist/index.js:6185:16)
+53 error     at async /home/vikms/Desktop/First party libraries/SDC/ticketing-598-software-division-components-npm/node_modules/.pnpm/p-pipe@3.1.0/node_modules/p-pipe/index.js:12:19

package/lerna.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
+  "version": "1.4.2",
+  "packages": ["projects/*"],
+  "npmClient": "pnpm",
+  "useNx": false,
+  "forcePublish": true
+}