= Utils

This module includes general-purpose Typescript/NodeJS utilities.

WARNING: Circa 2023-01(Jan), npx np has faced issues. + Manually update version, then: + npm publish --access public

== Module Publication

[%autowidth, frame="none", grid="none", cols=">h,<"] |===

|npm run installLatest |Updates library dependencies.

|npm run doAll |Build typescript and run available jests.

|git commit |Commit all local changes and push them to origin/main.

|npm login |Use the provided link to open a browser and authenticate with npm.

|npx np |Trigger the np publisher. + Review the list of files (if any) that are being published for the first time.

|select semver |np clarifies whether the update is a patch, minor, major, ... + np will insist you stash any local, uncommitted changes!

|Provide one-time password |After running tests, np will seek a fresh one-time password when 'publishing'. + ✔ Prerequisite check + ✔ Git + ✔ Installing dependencies using npm + ✔ Running tests using npm + ✔ Bumping version using npm <- one-time password required here + ✔ Publishing package using npm <- np may hang and still be successful! + ✔ Pushing tags +

|Review Versions |https://www.npmjs.com/search?q=%40opigence%2Futils

|Remove a Version |npm unpublish @opigence.com/[email protected] --force

|Deprecate a Version |npm deprecate -f @opigence.com/[email protected] "this package has been deprecated"

|===

WARNING: The documentation below (and other project adocs) needs to be reviewed/updated!

== Antora Support The primary focus is to facilitate automatically generating an _antora/ directory that complies with Antora's standard directory requirements.

=== Included AsciiDoc Files One symbolic link is created for each discovered AsciiDoc file.

=== Included "Snippet" Files One AsciiDoc file is created per Snippet source file.

Snippet source files are non-AsciiDoc files (i.e., no .adoc suffix) that embed snippets. Snippets are lines with one of the following snippet-prefixes.

[horizontal] //adoc|:: Snippet prefix for files using //-delimited comments #adoc|:: Snippet prefix for files using #-delimited comments

=== Optional TsDoc Inclusion The typedoc npm module generates HTML from embedded TsDoc notation. Support exists for generating thus HTML into _antora/ and referencing it in the generated Antora navigation file.

=== Optional Code Coverage Inclusion Support exists for copying Code Coverage HTML into _antora/ and referencing it in the generated Antora navigation file.

== KNOWN ISSUES There's no clean way of adding npm run antora to .git/hooks/pre-commit without creating some issues. For example: Tools like VsCode do not show any messages written to the console. Rebuilding Antora (a) takes time and (b) it takes VsCode a little time to detect any file changes and reconcile "Changes" to "Staged Changes".

Tactically, an Antora rebuild is being added as a pre-commit on a trial basis.

== Trigger on Git Pre-Commit In order to ensure that antora/ is up-to-date, a Git pre-commit hook is defined.

..git/hooks/pre-commit

#!/bin/sh npm run antora

NOTE: Watch for the case where .git/hooks/pre-commit reverts to non-executable.

== LICENSE

Copyright (C) 2023-Present Wesley M. Conner DBA Opigence Tech License: Apache-2.0 See LICENSE.txt