chore: clean up repository tooling and release checks

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/ISSUE_TEMPLATE/bug_report.md

@@ -26,9 +26,9 @@ assignees: ''
 
 يرجى توضيح البيئة التي كنت تستخدمها عند حدوث المشكلة. يمكن ذلك أن يشمل:
 
--   بيئة التشغيل (مثل Node.js 22.x، أو المتصفح Chrome، أو Next.js / Vite)
--   إصدار الحزمة arabic-services (مثل 1.1.0)
--   نظام التشغيل (مثل Windows أو Linux أو macOS)
+- بيئة التشغيل (مثل Node.js 22.x، أو المتصفح Chrome، أو Next.js / Vite)
+- إصدار الحزمة arabic-services (مثل 1.1.0)
+- نظام التشغيل (مثل Windows أو Linux أو macOS)
 
 ## السلوك المتوقع (Expected Behavior)
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -30,6 +30,6 @@ assignees: ''
 
 هل تعتبر هذه الميزة ذات أهمية عالية أم منخفضة؟ يرجى تحديد درجة الأهمية بوضوح.
 
--   [ ] عالية الأهمية
--   [ ] متوسطة الأهمية
--   [ ] منخفضة الأهمية
+- [ ] عالية الأهمية
+- [ ] متوسطة الأهمية
+- [ ] منخفضة الأهمية

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,27 +1,16 @@
-## وصف الفكرة (Feature Idea)
+## ملخص التغيير (Summary)
 
-يرجى وصف الفكرة أو الميزة الجديدة التي تود إضافتها إلى المشروع بوضوح هنا. يمكن أن تكون هذه الفكرة ميزة جديدة أو تحسين على ميزة موجودة.
+اشرح المشكلة والتغيير الناتج، واربط الـIssue إن وجد.
 
-## الهدف (Goal)
+## التوافق (Compatibility)
 
-ما الهدف من هذه الميزة؟ ما الفائدة التي ستقدمها للمستخدمين والمطورين؟ يرجى توضيح الفائدة والقيمة المضافة التي ستحققها هذه الفكرة.
+وضّح أي تأثير على الـAPI أو القيم الافتراضية أو النتائج أو طرق استيراد الحزمة.
 
-## سياق الاستخدام (Use Case)
+## التحقق (Validation)
 
-يرجى توضيح سيناريوهات الاستخدام التي تتطلب هذه الميزة. ما هي الحالات التي ستُستخدم فيها؟ وما الأوضاع التي تحتاج إلى هذه الميزة؟
+اذكر الأوامر والنتائج وأي فحوص لم تُنفذ.
 
-## توصيف تفصيلي (Detailed Description)
-
-يرجى تقديم توصيف مفصل لكيفية عمل هذه الميزة والتفاصيل الفنية اللازمة لتنفيذها. يمكنك توضيح واجهة المستخدم المقترحة، وكيفية تفاعل المستخدم مع الميزة، وأي تأثيرات قد تكون لها على المشروع.
-
-## السياق الإضافي (Additional Context)
-
-هل هناك أي سياق إضافي يمكن أن يساعد في فهم الفكرة وأهميتها؟ يمكنك توضيح المزيد من التفاصيل التقنية أو وضع روابط لموارد مرتبطة بالفكرة.
-
-## الأهمية (Priority)
-
-هل تعتبر هذه الميزة ذات أهمية عالية أم منخفضة؟ يرجى تحديد درجة الأهمية بوضوح.
-
--   [ ] عالية الأهمية
--   [ ] متوسطة الأهمية
--   [ ] منخفضة الأهمية
+- [ ] `npm run format:check`
+- [ ] `npm run lint`
+- [ ] `npm test` (source tests, build, artifact tests)
+- [ ] تحديث التوثيق و`[Unreleased]` عند الحاجة، مع الحفاظ على الإصدارات السابقة.

.github/workflows/ci.yml

@@ -32,5 +32,5 @@ jobs:
             - name: Install dependencies
               run: npm ci
 
-            - name: Run lint, build, and tests
-              run: npm run lint && npm run build && npm test
+            - name: Check formatting, lint, and tests
+              run: npm run format:check && npm run lint && npm test

.github/workflows/npm-publish.yml

@@ -1,48 +1,68 @@
 name: Publish Package to npmjs
 
-# Trigger this workflow when a release is published
 on:
     release:
         types: [published]
     workflow_dispatch:
+        inputs:
+            tag:
+                description: 'Existing release tag to publish (for example, v1.2.0)'
+                required: true
+                type: string
 
 jobs:
     build:
-        # Specify the runner environment
         runs-on: ubuntu-latest
         permissions:
             contents: write
             id-token: write
+        env:
+            RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
 
         steps:
-            # Step 1: Check out the repository's code
             - name: Check out repository
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ env.RELEASE_TAG }}
+                  fetch-depth: 0
 
-            # Step 2: Set up Node.js environment
             - name: Set up Node.js
               uses: actions/setup-node@v4
               with:
-                  node-version: '24' # Node 24 includes npm 11+ required for OIDC Trusted Publishing
+                  node-version: '24'
+
+            - name: Verify release tag and version
+              run: |
+                  node <<'NODE'
+                  const { execFileSync } = require('node:child_process');
+                  const { version } = require('./package.json');
+                  const tag = process.env.RELEASE_TAG;
+                  if (tag !== `v${version}`) {
+                    throw new Error('Release tag must match the package.json version');
+                  }
+                  const commit = ref => execFileSync('git', ['rev-parse', '--verify', ref], { encoding: 'utf8' }).trim();
+                  if (commit(`refs/tags/${tag}^{commit}`) !== commit('HEAD')) {
+                    throw new Error('The checked-out commit must match the release tag');
+                  }
+                  NODE
 
-            # Step 3: Install dependencies using npm ci
             - name: Install dependencies
               run: npm ci
 
-            # Step 4: Build package and bundles
-            - name: Build package and bundles
-              id: build
-              run: npm run build
+            - name: Check formatting, lint, and tests
+              id: verify
+              run: npm run format:check && npm run lint && npm test
 
-            # Step 5: Publish the package to npm using Trusted Publishing (OIDC)
             - name: Publish to npm
-              run: npm publish --provenance --access public
+              # Verification already built and tested these artifacts; local publishing keeps prepublishOnly.
+              run: npm publish --provenance --access public --ignore-scripts
 
-            # Step 6: Upload bundle assets to release
             - name: Upload bundle assets to release
-              if: always() && steps.build.outcome == 'success'
+              if: always() && steps.verify.outcome == 'success'
               uses: softprops/action-gh-release@v2
               with:
+                  tag_name: ${{ env.RELEASE_TAG }}
+                  fail_on_unmatched_files: true
                   files: |
                       dist/umd/arabic-services.umd.js
                       dist/umd/arabic-services.umd.js.map

.gitignore

@@ -15,6 +15,7 @@ Thumbs.db
 
 # Test results and coverage
 coverage/
+.tree-shaking-*/
 *.test.ts.snap
 
 # Environment variables

.npmignore

@@ -1,7 +1,6 @@
 # Testing
-__tests__/
+tests/
 coverage/
-jest.config.js
 *.test.ts
 *.test.ts.snap
 

.prettierignore

@@ -1 +1,3 @@
 /dist
+CHANGELOG.md
+package-lock.json

AGENTS.md

@@ -16,15 +16,19 @@ A zero-runtime-dependency TypeScript library for Arabic text in Node.js and brow
 - Respect Unicode code points, UTF-16 indices and combining marks. Make lossy normalization explicit.
 - Do not describe affix stripping as morphological analysis or visual obfuscation as encryption.
 - Add focused regression tests for behavior changes, including mixed scripts, empty input and adversarial regex cases where relevant.
+- Preserve intentional randomness in visual obfuscation; make randomized tests reproducible without changing production behavior.
 - Update affected English/Arabic docs and release notes. Follow existing contribution conventions.
+- Use Conventional Commits and record notable changes under `[Unreleased]` in `CHANGELOG.md`.
 - Document actual APIs and commands; clearly label proposed features. Do not invent capabilities or performance claims.
 - Verify third-party licenses; do not copy implementations or expose secrets/private input.
 - Do not manually edit generated output or lockfiles unless requested. Ask before commits, pushes, publishing or destructive operations.
 
 ## Validation
 
 - Use installed tools; start with the narrowest relevant lint, type or test check, then broaden when justified. Current scripts include `npm run lint` and `npm test`.
+- Use `npm run test:unit` for source tests without a build. `npm test` runs source tests, builds once, then runs `test:artifacts` against compiled files and package contents.
 - For export/build changes, verify fresh package artifacts and declarations through CJS, ESM and browser consumers; source tests alone are insufficient. Inspect build/cleanup scripts first.
 - Check bundle size and tree-shaking when changing imports, exports or dependencies; measure before claiming improvements.
 - For documentation-only changes, check formatting and references without building. Avoid autofix during read-only reviews.
+- Preserve published changelog entries and both Gregorian and Hijri dates; add new release notes under `[Unreleased]` only. Exclude `CHANGELOG.md` from bulk formatting.
 - Review the final diff. Report exact checks, results and skipped validation; distinguish evidence from assumptions.

CHANGELOG.md

@@ -6,11 +6,32 @@
 - Integration tests for CJS, ESM, and browser UMD artifacts.
 - Arabic NLP boundary and ReDoS resilience test suites.
 - Direct CDN links (jsdelivr & unpkg) and GitHub release bundle guide in documentation.
+- JavaScript source maps and TypeScript declaration maps for CommonJS and native ESM builds, plus source maps for UMD and ESM browser bundles ([PR #40](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/pull/40)).
+- Original TypeScript source files in the npm package and companion browser bundle maps in GitHub release uploads ([PR #40](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/pull/40)).
+- Regression tests for invalid obfuscation levels, Arabic character variants, and out-of-range `setCharAt` indices ([PR #36](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/pull/36), [PR #37](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/pull/37)).
+
+- Automated checks for npm package contents, source/declaration map references, and real tree shaking of built ESM consumers.
 
 ### Changed
 - Modularized monolithic `src/scripts/scripts.ts` into focused single-responsibility files (`tashkeel.ts`, `old-arabic.ts`, `tashfeer.ts`, `affixes.ts`, `letters.ts`) while keeping public exports and backward compatibility completely unchanged.
 - Relocated standalone browser demo to `examples/browser/index.html`.
 - Unified CI workflow across Node.js 22.x and 24.x with ESLint.
+- Expanded lint commands from `src/` to all non-ignored repository files.
+- Declared ES2020 and DOM type libraries in the TypeScript configuration to resolve missing API type diagnostics in editors ([PR #38](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/pull/38)).
+- Updated the npm publishing workflow to Node.js 24.
+- Consolidated agent instructions in `AGENTS.md`.
+
+- Separated source and artifact test commands; `npm test` now builds once between the two suites.
+- Standardized LF line endings, refreshed contribution and PR guidance, and clarified visual-obfuscation terminology.
+- Release publishing now validates the tag/version and runs formatting, lint, and tests before publishing the verified build.
+
+### Fixed
+- Prevent invalid levels from hanging `tashfeer`, `tashfeerBannedWords`, and `toOldArabicAndTashfeerBannedWords`: non-number values throw `TypeError`; negative, fractional, and non-finite numbers throw `RangeError`. Random-index generation handles empty input and caps the requested count at the word length ([#35](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/issues/35), [PR #36](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/pull/36)).
+- Attempt browser bundle uploads after a successful build even if npm publishing fails ([commit 598035a](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/commit/598035a)).
+
+- Removed the unused `dev` command, which depended on the uninstalled `ts-node` runner.
+
+[Full Changelog](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/compare/v1.1.0...main)
 
 ## [1.1.0](https://github.com/Seen-Arabic/Arabic-Services-JavaScript/releases/tag/v1.1.0) - 2026-10-14 (03 Jumada al-Awwal 1448)