@zairakai/js-dev-tools 1.0.0

package/.editorconfig

@@ -0,0 +1,86 @@
+# ===============================================
+# EDITORCONFIG
+# Coding standards for consistent formatting
+# ===============================================
+
+root = true
+
+# ======================
+# ALL FILES
+# ======================
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# ======================
+# MARKDOWN FILES
+# ======================
+[markdown]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = false
+insert_final_newline = true
+max_line_length = 120
+
+[*.md]
+trim_trailing_whitespace = false
+
+# ======================
+# SHELL SCRIPTS
+# ======================
+[*.sh]
+end_of_line = lf
+
+# ======================
+# YAML FILES
+# ======================
+[*.{yml,yaml}]
+indent_size = 2
+
+[docker-compose.yml]
+indent_size = 4
+
+# ======================
+# BUILD FILES
+# ======================
+[Makefile]
+indent_style = tab
+
+[Dockerfile*]
+indent_size = 4
+
+# ======================
+# CONFIGURATION FILES
+# ======================
+[*.{ini,conf}]
+indent_size = 4
+
+# ======================
+# FRONTEND FILES
+# ======================
+[*.json]
+indent_size = 2
+
+# ======================
+# PHP FILES
+# ======================
+[*.php]
+indent_size = 4
+max_line_length = 120
+
+# ======================
+# Test FILES
+# ======================
+[*.feature]
+charset = utf-8
+gherkin_indent_feature_children = true
+gherkin_indent_steps = true
+gherkin_indent_datatable = true
+gherkin_indent_docstring = true
+gherkin_indent_examples_table = true
+gherkin_table_cell_padding_size = 2
+gherkin_table_cell_right_align_numeric_content = true

package/.gitlab/ci/pipeline-js-app.yml

@@ -0,0 +1,75 @@
+# ================================
+# PIPELINE TEMPLATE — Laravel App JS/Frontend
+# ================================
+# Provides JS/Frontend CI jobs for a Laravel application.
+# Includes pipeline-js-package.yml (all js: jobs) and disables the
+# package-specific stages (build, publish, release) not relevant for apps.
+#
+# PHP jobs come from laravel-dev-tools (pipeline-laravel-app.yml).
+# All js: job names never conflict with php: job names.
+#
+# Fullstack usage (recommended — single include):
+# ─────────────────────────────────────────────────────
+#   include:
+#     - project: 'zairakai/php-packages/laravel-dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-laravel-fullstack.yml'
+#
+# Standalone usage (JS side only, alongside a custom PHP pipeline):
+# ─────────────────────────────────────────────────────
+#   include:
+#     - project: 'zairakai/npm-packages/dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-js-app.yml'
+#
+#   variables:
+#     CACHE_KEY: "my-app-v1"
+# ================================
+
+include:
+  # All js: jobs come from pipeline-js-package.yml — no duplication.
+  - project: "zairakai/npm-packages/dev-tools"
+    ref: main
+    file: ".gitlab/ci/pipeline-js-package.yml"
+
+# ================================
+# STAGES
+# ================================
+# Merges with PHP pipeline stages — GitLab deduplicates identical names.
+# The build/publish/release stages from pipeline-js-package.yml are kept
+# in the merged list but stay empty (jobs below are disabled).
+stages:
+  - security
+  - install
+  - validate
+  - quality
+  - test
+  - deploy
+  - metrics
+
+# ================================
+# VARIABLES
+# ================================
+variables:
+  # Default cache key for app context (overridden per project via CACHE_KEY).
+  CACHE_KEY: "zairakai-laravel-app"
+
+  # Note: GIT_CLEAN_FLAGS intentionally NOT set here.
+  # pipeline-laravel-fullstack.yml sets the combined value to preserve
+  # both vendor/ and node_modules/.
+
+# ================================
+# DISABLE package-specific jobs
+# Not relevant for a Laravel app (no npm publish or GitLab release).
+# ================================
+js:build:
+  rules:
+    - when: never
+
+js:publish:
+  rules:
+    - when: never
+
+js:release:
+  rules:
+    - when: never

package/.gitlab/ci/pipeline-js-package.yml

@@ -0,0 +1,360 @@
+# ================================
+# PIPELINE TEMPLATE — NPM Package
+# ================================
+# Shared pipeline template for NPM packages in the Zairakai namespace.
+# Self-contained: anchors and jobs are all in this single file.
+# YAML anchors do not survive cross-file include: — this is a YAML parser
+# limitation, not a GitLab one. Everything is therefore kept here.
+#
+# All job names are prefixed js: to avoid any collision with PHP or custom
+# jobs when this template is combined with other templates.
+# pipeline-js-app.yml (fullstack context) includes this file directly — no duplication.
+#
+# USAGE in a consumer project:
+# ─────────────────────────────────────────
+#   include:
+#     - project: 'zairakai/npm-packages/dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-js-package.yml'
+#
+#   variables:
+#     CACHE_KEY: "my-package-v1"
+#     NPM_PACKAGE_NAME: "@myorg/my-package"
+#
+# FOR dev-tools ITSELF (self-hosted mode):
+# ─────────────────────────────────────────────────────
+#   include:
+#     - local: '.gitlab/ci/pipeline-js-package.yml'
+#
+#   variables:
+#     CACHE_KEY: "dev-tools-v1"
+#     NPM_PACKAGE_NAME: "@zairakai/js-dev-tools"
+#     DEV_TOOLS_SCRIPTS: "scripts"
+# ================================
+
+include:
+  - template: Jobs/Secret-Detection.gitlab-ci.yml
+
+# ================================
+# WORKFLOW
+# ================================
+workflow:
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
+    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
+    - if: $CI_COMMIT_REF_NAME =~ /^feature\// || $CI_COMMIT_REF_NAME =~ /^fix\// || $CI_COMMIT_REF_NAME =~ /^hotfix\//
+    - when: never
+
+# ================================
+# STAGES
+# ================================
+stages:
+  - security
+  - install
+  - validate
+  - quality
+  - test
+  - build
+  - publish
+  - release
+
+# ================================
+# DEFAULT VARIABLES
+# ================================
+variables:
+  # ── OVERRIDE PER PROJECT ──────────────────────────────────────────────────
+  CACHE_KEY: "zairakai-npm-package"
+  NPM_PACKAGE_NAME: "@zairakai/package"
+
+  # Paths to dev-tools scripts.
+  # Consumer projects do NOT need to override these.
+  # dev-tools itself overrides them in its own .gitlab-ci.yml.
+  DEV_TOOLS_SCRIPTS: "node_modules/@zairakai/js-dev-tools/scripts"
+
+  # ── NODE ──────────────────────────────────────────────────────────────────
+  NODE_VERSION: "22"
+  NODE_IMAGE: "zairakai/node:latest-dev"
+  NODE_TEST_IMAGE: "zairakai/node:latest-test"
+  SHELLCHECK_IMAGE: "koalaman/shellcheck-alpine:v0.10.0"
+  RELEASE_CLI_IMAGE: "registry.gitlab.com/gitlab-org/release-cli:v0.18.0"
+  ALPINE_IMAGE: "alpine:3.18"
+
+  # ── GIT ───────────────────────────────────────────────────────────────────
+  GIT_DEPTH: 1
+  GIT_STRATEGY: fetch
+  GIT_CLEAN_FLAGS: "-ffdx -e node_modules/ -e .npm/"
+
+  # ── SECURITY ──────────────────────────────────────────────────────────────
+  SECRET_DETECTION_EXCLUDED_PATHS: "node_modules/,dist/,build/,coverage/"
+
+# ================================
+# ANCHORS
+# ================================
+.base_job: &base_job
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+
+.cache_node: &cache_node
+  cache:
+    key:
+      files:
+        - package-lock.json
+      prefix: $CACHE_KEY
+    paths:
+      - node_modules/
+      - .npm/
+    policy: pull
+
+.cache_node_push: &cache_node_push
+  cache:
+    key:
+      files:
+        - package-lock.json
+      prefix: $CACHE_KEY
+    paths:
+      - node_modules/
+      - .npm/
+    policy: pull-push
+
+.job_node: &job_node
+  <<: [*base_job, *cache_node]
+  image: ${NODE_IMAGE}
+  before_script:
+    - node --version
+    - npm --version
+
+# ================================
+# SECURITY
+# ================================
+secret_detection:
+  stage: security
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
+    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
+
+# ================================
+# INSTALL
+# ================================
+js:install:
+  <<: [*base_job, *cache_node_push]
+  stage: install
+  image: ${NODE_IMAGE}
+  script:
+    - npm ci --cache .npm --prefer-offline
+    - |
+      if [ -f /lib/ld-musl-x86_64.so.1 ]; then
+        npm install --no-save @oxc-resolver/binding-linux-x64-musl @rollup/rollup-linux-x64-musl
+      fi
+  artifacts:
+    paths:
+      - node_modules/
+    expire_in: 1 hour
+
+# ================================
+# VALIDATE
+# ================================
+js:validate:markdownlint:
+  <<: [*base_job, *cache_node]
+  stage: validate
+  image: ${NODE_IMAGE}
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/markdownlint.sh"
+
+js:validate:shellcheck:
+  <<: *base_job
+  stage: validate
+  image: ${SHELLCHECK_IMAGE}
+  before_script:
+    - apk add --no-cache bash
+  script:
+    - |
+      if [[ -d scripts/ ]]; then
+        bash "$DEV_TOOLS_SCRIPTS/validate-shellcheck.sh"
+      else
+        echo "No scripts/ directory found — skipping ShellCheck"
+      fi
+
+# ================================
+# QUALITY
+# ================================
+js:quality:lint:
+  <<: *job_node
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/eslint.sh"
+  artifacts:
+    reports:
+      junit: build/reports/eslint.xml
+    paths:
+      - build/reports/
+    expire_in: 1 week
+    when: always
+
+js:quality:format:
+  <<: *job_node
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/prettier.sh"
+
+js:quality:stylelint:
+  <<: *job_node
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/stylelint.sh"
+
+js:quality:typecheck:
+  <<: *job_node
+  stage: quality
+  script:
+    - |
+      if [ -f tsconfig.json ] && [ -f node_modules/.bin/tsc ]; then
+        bash "$DEV_TOOLS_SCRIPTS/typecheck.sh"
+      else
+        echo "TypeScript not configured — skipping (add tsconfig.json + typescript to devDependencies)"
+      fi
+
+js:quality:knip:
+  <<: *job_node
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/knip.sh"
+
+js:quality:bats:
+  <<: [*base_job, *cache_node]
+  stage: quality
+  image: ${ALPINE_IMAGE}
+  before_script:
+    - apk add --no-cache bash bats
+  script:
+    - |
+      if [[ -d tests/bats ]]; then
+        bats tests/bats --recursive
+      else
+        echo "No BATS tests found — skipping"
+      fi
+
+js:quality:outdated:
+  <<: *job_node
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/outdated.sh"
+  artifacts:
+    paths:
+      - build/reports/npm-outdated.json
+    expire_in: 1 week
+    when: always
+
+# ================================
+# TEST
+# ================================
+js:test:
+  <<: [*base_job, *cache_node]
+  stage: test
+  image: ${NODE_TEST_IMAGE}
+  script:
+    - CI=true bash "$DEV_TOOLS_SCRIPTS/test.sh"
+  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
+  artifacts:
+    reports:
+      junit: build/coverage/junit.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: build/coverage/cobertura-coverage.xml
+    paths:
+      - build/coverage/
+    expire_in: 1 week
+    when: always
+
+# ================================
+# BUILD
+# ================================
+js:build:
+  <<: *job_node
+  stage: build
+  script:
+    - |
+      if { [ -f node_modules/.bin/tsup ] || [ -f node_modules/.bin/tsc ]; } && [ -f tsconfig.json ]; then
+        bash "$DEV_TOOLS_SCRIPTS/build.sh"
+      else
+        echo "No TypeScript builder configured — skipping (install tsup or typescript)"
+      fi
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+    when: on_success
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
+
+# ================================
+# PUBLISH
+# ================================
+js:publish:
+  <<: [*base_job, *cache_node]
+  stage: publish
+  image: ${NODE_IMAGE}
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  script:
+    - |
+      if [[ -z "${NPM_TOKEN:-}" ]]; then
+        echo "ERROR: NPM_TOKEN is not set or empty"
+        echo "Go to: GitLab → Settings → CI/CD → Variables → add NPM_TOKEN (type: Variable, protected, masked)"
+        exit 1
+      fi
+    - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "${CI_PROJECT_DIR}/.npmrc"
+    - |
+      if [[ $CI_COMMIT_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+.*$ ]]; then
+        echo "Publishing ${NPM_PACKAGE_NAME}@${CI_COMMIT_TAG#v} to npm..."
+        npm version "${CI_COMMIT_TAG#v}" --no-git-tag-version --allow-same-version
+        npm publish --access public
+      else
+        echo "Invalid tag format: ${CI_COMMIT_TAG}. Expected: v1.0.0"
+        exit 1
+      fi
+  environment:
+    name: production
+    url: https://www.npmjs.com/package/${NPM_PACKAGE_NAME}
+
+# ================================
+# RELEASE
+# ================================
+js:release:
+  <<: *base_job
+  stage: release
+  image: ${RELEASE_CLI_IMAGE}
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  before_script:
+    - apk add --no-cache bash git jq
+    - git config --global --add safe.directory '*'
+    - git config --global user.name "GitLab CI"
+    - git config --global user.email "ci@gitlab.com"
+  script:
+    - |
+      PREVIOUS_TAG=$(git tag --sort=-version:refname | head -n 2 | tail -n 1 || echo "")
+      if [[ -n "$PREVIOUS_TAG" && "$PREVIOUS_TAG" != "$CI_COMMIT_TAG" ]]; then
+        COMMITS=$(git log --pretty=format:"- %s" "${PREVIOUS_TAG}..${CI_COMMIT_TAG}" | head -20)
+      else
+        COMMITS="- Initial release"
+      fi
+      cat > release_notes.md << NOTES
+      ## ${CI_COMMIT_TAG}
+
+      ${COMMITS}
+      NOTES
+      release-cli create \
+        --tag-name "${CI_COMMIT_TAG}" \
+        --name "Release ${CI_COMMIT_TAG}" \
+        --description "$(cat release_notes.md)" \
+        --assets-link "{\"name\":\"npm\",\"url\":\"https://www.npmjs.com/package/${NPM_PACKAGE_NAME}/v/${CI_COMMIT_TAG#v}\"}"
+  artifacts:
+    paths:
+      - release_notes.md
+    expire_in: 1 year

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stanislas Poisson (Zairakai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.