@renault-digital/bash-base 2.4.1 → 2.5.1

package/CONTRIBUTING.md

@@ -7,21 +7,93 @@
 
 This project and everyone participating in it is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
 
+## CI test matrix
+
+Use the [CI test matrix](docs/coverage.md#ci-test-matrix) to distinguish runner
+operating systems, tested interpreters, full-suite and selected test runs, and
+coverage report destinations. Keep it aligned with changes to the workflow and
+test entry points. A 100% line union is not a per-environment test guarantee.
+
 ## Submit an issue
 
-For bug report or enhancement suggestion, you can submit a  [GitHub issue](https://guides.github.com/features/issues/). 
+Search the existing issues before opening a report or suggestion on the
+[issues page](https://github.com/renault-digital/bash-base/issues/new/choose).
+
+For a bug report, include a minimal reproduction, expected and actual behavior,
+the Bash-base version or commit, the actual Shell and its version, the operating
+system, and the installation/loading method. Include stdout, stderr and exit
+status when relevant. Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)
+and remove credentials and other sensitive information from examples and logs.
+
+For a feature request, describe the task and the difficulty first. Unknown
+implementation details are not a reason to withhold a useful use case.
+
+## Proposing a feature
+
+Consult the [roadmap](docs/roadmap.md) for current priorities, dependencies and
+acceptance criteria. A roadmap entry is an investigation direction, not an
+approved API or a guaranteed release. Record actionable tasks and results in
+issues and pull requests.
+
+Start with the [design principles](docs/design-principles.md). Bash-base accepts
+features to reduce recurring command-composition and scripting costs, not to
+maximize the number of helpers or reproduce another language's standard library.
+
+Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and
+describe a concrete task, the difficulty it creates, and the approaches already
+considered. A request does not need a finished API design or implementation;
+identify unknowns explicitly so they can be discussed.
 
-Before propose a feature, a good understanding of the requested feature may be crucial for the acceptance of the proposal.
+Before merging an implementation, the contributor and maintainer should resolve:
 
-Firstly, search if your idea is not already created by others, then fill the information on the [issues page](https://github.com/renault-digital/bash-base/issues/new/choose).
+| Question | Evidence expected for implementation review |
+| --- | --- |
+| What recurring problem does this solve? | A representative use case and the research, implementation, verification or maintenance work it avoids. |
+| Why does this belong in Bash-base? | A clear connection to command arguments, outputs, execution or automation logic; comparison with built-ins, existing helpers and external tools. |
+| What is the public contract? | Inputs, outputs, exit statuses, side effects, input boundaries and a realistic composition example. |
+| What supports its reliability? | Relevant regression, boundary-input and supported-environment tests, including error paths. |
+| What changes for existing users? | A compatibility assessment, any migration requirements, dependencies and maintenance costs. |
+
+Preserve the existing regression and mandatory coverage gates. Coverage is
+necessary evidence, not proof of all branches, inputs or security properties.
+Do not relax a gate or silently change an existing API to make a new feature fit.
+
+Document public helper behavior in its source comments as required by the
+existing LiveDoc workflow. Keep shared design principles in the design-principles
+reference and feature-specific rationale in the issue or pull request; neither
+replaces generated API documentation.
 
 ## Code Contribution
 
-If you want, aside from submitting a github issue, a good pull request is a fantastic help.
+Code, tests, documentation and CI improvements can be submitted through pull requests.
 
 A pull request should remain focused in scope and avoid containing unrelated commits.
 
-#### Understand the technology stack
+### Validation and compatibility
+
+Behavior changes must include appropriate regression and boundary tests for the
+supported environments. Preserve existing Bash behavior and the documented
+Bash/zsh compatibility boundary; proposed design principles do not silently
+change a current helper's contract.
+
+Keep the existing regression, compatibility and mandatory 100% measurable-line
+coverage gates. Do not weaken a gate, hide uncovered code or add meaningless
+tests merely to obtain a passing result. Coverage does not establish complete
+branch coverage, arbitrary-input safety or the absence of security defects.
+
+Documentation-only changes do not require artificial test-suite changes when
+executable behavior is unchanged. Explain that scope in the pull request and
+validate the changed text, examples, links or metadata as appropriate. This is
+not an exemption from the required CI status checks or coverage gate.
+
+Record the commands actually run, their results, and relevant Shell/OS versions.
+Distinguish completed checks from pending CI and checks that were not run. Do
+not equate a local check or a release preview with a successful real publish.
+
+Review the current release configuration before merging, including documentation
+changes. Do not assume a `docs:` commit is excluded from release automation.
+
+### Understand the technology stack
 
 - Works with git, npm and docker
 
@@ -32,7 +104,7 @@ A pull request should remain focused in scope and avoid containing unrelated com
 - BDD
     - BDD test with [ShellSpec](https://shellspec.info)
     - Code coverage with [Kcov](http://simonkagstrom.github.io/kcov/index.html) and [codecov](https://codecov.io)
-    - 100% coverage
+    - 100% measurable-source-line coverage under the required coverage gate
 
 - Respect [Semantic Versioning 2.0.0](https://semver.org/) and [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
     - Help input commit message 
@@ -61,7 +133,7 @@ A pull request should remain focused in scope and avoid containing unrelated com
 - CICD Workflow config with [NPM](https://docs.npmjs.com/about-npm/) and [Github actions](https://docs.github.com/en/actions)
     
 
-#### Notes
+### Notes
 
 - in commit message template, the default issuePrefixes: `['#']`
 
@@ -70,7 +142,7 @@ A pull request should remain focused in scope and avoid containing unrelated com
 - Don't modify the files `bin/`, `man/` and `docs/references.md`, they will generated automatically by semantic-release.
 
 
-#### How to do it ?
+### How to do it?
 
 1. Submit an issue, get the issue number, and assign it to you.
 
@@ -88,7 +160,7 @@ A pull request should remain focused in scope and avoid containing unrelated com
     npm ci
     ```
 
-1. Modify the code. Remember to write / update the tests for the proposed evolution, 100% test coverage is required, as every function will be used by users, we need to ensure its accuracy.
+1. Make the focused change. Add or update tests for behavior changes and preserve the mandatory coverage gate. For documentation-only changes, follow the validation requirements above instead of adding unrelated tests.
 
 1. Commit your changes in logical chunks. Please see the [commit message guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines).
 
@@ -109,7 +181,8 @@ A pull request should remain focused in scope and avoid containing unrelated com
    npm test
    npm run lint
    # npm run lint:commit
-   # npm run test:coverage # to be sure coverage 100%
+   # Optional local coverage diagnostic; not a replacement for the required gate:
+   # npm run test:coverage
    ```
     
 1. Open a pull request with a clear title and description in template

package/README.md

@@ -3,7 +3,7 @@
 [![License](https://img.shields.io/github/license/renault-digital/bash-base.svg)](https://github.com/renault-digital/bash-base/blob/master/LICENSE)
 [![GitHub top language](https://img.shields.io/github/languages/top/renault-digital/bash-base.svg)](https://github.com/renault-digital/bash-base/search?l=Shell)
 [![codecov](https://codecov.io/gh/renault-digital/bash-base/branch/master/graph/badge.svg)](https://codecov.io/gh/renault-digital/bash-base)
-[![GitHub Actions Status](https://img.shields.io/github/workflow/status/renault-digital/bash-base/cicd?label=GithubActions)](https://github.com/renault-digital/bash-base/actions)
+[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/renault-digital/bash-base/cicd.yml?branch=master&event=push&label=GitHub%20Actions)](https://github.com/renault-digital/bash-base/actions/workflows/cicd.yml)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 [![GitHub release](https://img.shields.io/github/release/renault-digital/bash-base.svg)](https://github.com/renault-digital/bash-base/releases/latest)
@@ -14,15 +14,83 @@
 
 ## Goal
 
-No more spending time searching the special ways of bash for basic operations like "how to replace a string in bash", then compare, choose, and test among many potential solutions.
+**Reusable Bash/zsh utilities for reliable command composition and automation.**
 
-Bash-base does this for you, you can just call the function here which is well tested and stable, and only focus you on the high level logic. Writing your script with less time, but more readability.
+Bash-base helps developers focus on what their shell scripts do, rather than
+repeatedly researching how every low-level operation should work.
 
-Available on [GitHub](https://github.com/renault-digital/bash-base), [NPM](https://www.npmjs.com/package/@renault-digital/bash-base) and [Docker Hub](https://hub.docker.com/r/renaultdigital/bash-base).
+Its starting point is a recurring cost: searching for a Shell implementation,
+comparing alternatives, experimenting with edge cases, and testing the result
+across supported environments. Saving a few lines is useful; avoiding that
+repeated implementation and verification work is the more important goal.
+
+Bash-base provides reusable, tested functions for expressing command-oriented
+logic through higher-level APIs. String and array operations support this goal:
+organizing command arguments, transforming outputs, and expressing automation
+logic. They are means to compose commands, not an attempt to build a complete
+general-purpose application framework in Shell.
+
+### Design priorities
+
+- **Pain-driven:** address recurring scripting problems, not a target number of
+  functions.
+- **Contract-driven:** make inputs, outputs, exit statuses and side effects
+  explicit, with interfaces that are understandable and work well together.
+- **Evidence-driven:** use regression and cross-shell tests to support
+  reliability claims within the documented compatibility boundary.
+- **Predictable reuse:** preserve existing behavior and favor fixed-version,
+  local loading where reproducible or offline execution matters.
+
+These priorities guide maintenance and new API design; they do not assert that
+every existing helper is side-effect-free or safe for arbitrary input. Read the
+[design principles](docs/design-principles.md),
+[API reference](docs/references.md), and
+[Bash/zsh compatibility contract](docs/bash-zsh-compatibility.md) for scope and
+boundaries. Proposed data types or helpers are not available APIs until they
+have been implemented, tested and documented.
+
+Available on [GitHub](https://github.com/renault-digital/bash-base),
+[NPM](https://www.npmjs.com/package/@renault-digital/bash-base), and
+[Docker Hub](https://hub.docker.com/r/renaultdigital/bash-base).
+
+
+## Bash and zsh compatibility
+
+The reusable functions in `src/` can be sourced by both **Bash** and **zsh**.
+This matters on macOS, where zsh is the default interactive shell: `source
+bash-base` is interpreted by the current shell, so the library itself must not
+rely on hidden Bash-only syntax.
+
+Existing Bash scripts and the Bash ShellSpec regression suite remain supported.
+A separate dual-shell compatibility gate runs the same core behavior under Bash
+and zsh.
+
+See [Bash and zsh compatibility](docs/bash-zsh-compatibility.md) for the exact
+contract, array portability boundary and test model.
 
 
 ## Test coverage report
-[![test coverage](https://codecov.io/gh/renault-digital/bash-base/graphs/tree.svg)](https://codecov.io/gh/renault-digital/bash-base)
+
+The `coverage-macos` CI job requires **100% of the measurable `src/*.sh` lines**
+to be covered by the validated union of Bash 3.2, Bash 5+, zsh and TTY runs on
+one source revision. This is **union line coverage**, not 100% coverage in each
+shell or a claim of complete branch/input coverage.
+
+Only that validated union is uploaded to Codecov. Invalid reports are rejected;
+a valid result below 100% is still reported, while the strict CI gate fails.
+The badge shows Codecov's latest processed result for `master`, not a hard-coded
+percentage. Click the tree below for file and line details, and check the commit
+SHA when comparing it with CI. Processing delays or a missing upload may leave
+an older result visible.
+
+[![test coverage](https://codecov.io/gh/renault-digital/bash-base/graphs/tree.svg)](https://app.codecov.io/gh/renault-digital/bash-base/tree/master/src)
+
+See the [CI test matrix](docs/coverage.md#ci-test-matrix) for runner, interpreter,
+test scope and report destinations.
+
+See [coverage collection, validation and reporting](docs/coverage.md) for the
+report contract, authentication setup and troubleshooting. CI also retains the
+raw reports, source hashes and logs in the `strict-macos-coverage` artifact.
 
 
 ## Quick start
@@ -53,6 +121,11 @@ Run it:
 
 ## Installation
 
+For reproducible or offline workflows, prefer a reviewed, fixed-version local
+copy. The methods below have different network and update behavior; read the
+Web installer and direct GitHub import notes before choosing a loading method.
+A remote-loading example is not an offline configuration.
+
 #### 1. Import from [docker hub](https://hub.docker.com/r/renaultdigital/bash-base)
 
 ```bash
@@ -228,11 +301,19 @@ See [reference](docs/references.md)
 See [example](example) folder, including the use case of <mark>**[Makefile](example/Makefile)**</mark>
 
 ## Specfile (test file)
-See [spec](spec) folder
+See [spec](spec) folder. Run `npm test` to execute the Bash/zsh compatibility gate followed by the existing Bash ShellSpec regression suite.
 
 ## Latest Update
 See [change log](CHANGELOG.md)
 
+## Roadmap
+
+See the [project roadmap](docs/roadmap.md) for prioritized investigation and
+future evolution of command composition, API contracts, shell portability,
+security, testing and distribution. The roadmap is not a commitment to ship
+particular features or versions. New proposals follow the
+[design principles](docs/design-principles.md).
+
 ## Contributing
 See [How to contribute](CONTRIBUTING.md)