@crashbytes/semantic-text-toolkit 1.0.1 → 1.0.2

package/.eslintrc.json

@@ -0,0 +1,24 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "env": {
+    "node": true,
+    "es2020": true,
+    "jest": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/no-namespace": "off"
+  },
+  "ignorePatterns": ["dist", "node_modules", "coverage"]
+}

package/.github/dependabot.yml

@@ -0,0 +1,50 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+    open-pull-requests-limit: 10
+    groups:
+      # Group all production dependencies
+      production-dependencies:
+        applies-to: version-updates
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+      
+      # Group development dependencies
+      development-dependencies:
+        applies-to: version-updates
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+    
+    # Auto-assign PRs
+    assignees:
+      - "MichaelEakins"
+    
+    # Labels for PRs
+    labels:
+      - "dependencies"
+      - "automated"
+    
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(actions)"

package/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Test with coverage
+        run: npm test -- --coverage
+
+      - name: Upload coverage reports
+        if: matrix.node-version == 20
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage/lcov.info
+          fail_ci_if_error: false

package/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+# CRITICAL: Required for npm Trusted Publishing (OIDC authentication)
+permissions:
+  contents: write  # Needed to create GitHub releases
+  id-token: write  # Needed for npm provenance/trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install latest npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Publish to npm with Provenance
+        run: npm publish --provenance --access public
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref }}
+          name: Release ${{ github.ref_name }}
+          body: |
+            See [CHANGELOG.md](https://github.com/CrashBytes/contentful-semantic-text-toolkit/blob/main/CHANGELOG.md) for details.
+          draft: false
+          prerelease: false

package/README.md

@@ -7,7 +7,7 @@ Production-grade semantic text analysis with embeddings, similarity computation,
 [![npm](https://img.shields.io/npm/v/@crashbytes/semantic-text-toolkit)](https://www.npmjs.com/package/@crashbytes/semantic-text-toolkit)
 [![npm](https://img.shields.io/npm/dm/@crashbytes/semantic-text-toolkit)](https://www.npmjs.com/package/@crashbytes/semantic-text-toolkit)
 [![npm bundle size](https://img.shields.io/bundlephobia/min/@crashbytes/semantic-text-toolkit)](https://bundlephobia.com/package/@crashbytes/semantic-text-toolkit)
-[![GitHub](https://img.shields.io/github/license/CrashBytes/contentful-semantic-text-toolkit)](./LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 ---
 

package/jest.config.js

@@ -0,0 +1,66 @@
+/**
+ * Jest Configuration
+ * 
+ * Architectural Principles:
+ * - Comprehensive coverage tracking
+ * - Reasonable timeout for ML model operations
+ * - Clear test organization patterns
+ * - Production-grade quality thresholds
+ */
+
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  
+  // Test discovery patterns
+  roots: ['<rootDir>/src'],
+  testMatch: [
+    '**/__tests__/**/*.test.ts',
+    '**/?(*.)+(spec|test).ts'
+  ],
+  
+  // Coverage configuration
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/__tests__/**',
+    '!src/index.ts', // Entry point excluded from coverage
+  ],
+  
+  // Quality thresholds - enforce production standards
+  coverageThreshold: {
+    global: {
+      branches: 90,
+      functions: 90,
+      lines: 90,
+      statements: 90,
+    },
+  },
+  
+  // Coverage reporting formats
+  coverageReporters: [
+    'text',           // Console output
+    'text-summary',   // Summary statistics
+    'lcov',           // CI integration
+    'html',           // Visual browser report
+  ],
+  
+  // Timeout configuration - ML operations require patience
+  testTimeout: 60000, // 60 seconds for model loading
+  
+  // Module resolution
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  
+  // Transform configuration
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+      },
+    }],
+  },
+  
+  // Setup files
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crashbytes/semantic-text-toolkit",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Production-grade semantic text analysis with embeddings, similarity, and vector operations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/__tests__/setup.ts

@@ -0,0 +1,43 @@
+/**
+ * Jest Test Setup
+ * 
+ * Global configuration and utilities for test environment.
+ * Executed once before test suite runs.
+ */
+
+// Extend Jest matchers if needed
+expect.extend({
+  toBeWithinRange(received: number, floor: number, ceiling: number) {
+    const pass = received >= floor && received <= ceiling;
+    if (pass) {
+      return {
+        message: () =>
+          `expected ${received} not to be within range ${floor} - ${ceiling}`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () =>
+          `expected ${received} to be within range ${floor} - ${ceiling}`,
+        pass: false,
+      };
+    }
+  },
+});
+
+// Custom type definitions for extended matchers
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      toBeWithinRange(floor: number, ceiling: number): R;
+    }
+  }
+}
+
+// Global test configuration
+process.env.NODE_ENV = 'test';
+
+// Increase timeout for CI environments
+if (process.env.CI) {
+  jest.setTimeout(120000); // 2 minutes for CI
+}

package/src/__tests__/types.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Types Test Suite
+ *
+ * Validation of type definitions and SemanticError class behavior.
+ */
+
+import { SemanticError, SemanticErrorCode } from '../types';
+
+describe('SemanticError', () => {
+  describe('constructor', () => {
+    it('creates error with code and message', () => {
+      const error = new SemanticError(
+        SemanticErrorCode.INVALID_INPUT,
+        'Invalid input provided'
+      );
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(SemanticError);
+      expect(error.code).toBe(SemanticErrorCode.INVALID_INPUT);
+      expect(error.message).toBe('Invalid input provided');
+      expect(error.name).toBe('SemanticError');
+    });
+
+    it('creates error with details', () => {
+      const error = new SemanticError(
+        SemanticErrorCode.DIMENSION_MISMATCH,
+        'Dimensions do not match',
+        { expected: 384, actual: 256 }
+      );
+
+      expect(error.details).toEqual({ expected: 384, actual: 256 });
+    });
+
+    it('creates error without details', () => {
+      const error = new SemanticError(
+        SemanticErrorCode.MODEL_NOT_LOADED,
+        'Model not loaded'
+      );
+
+      expect(error.details).toBeUndefined();
+    });
+  });
+
+  describe('error codes', () => {
+    it('has MODEL_NOT_LOADED code', () => {
+      expect(SemanticErrorCode.MODEL_NOT_LOADED).toBe('MODEL_NOT_LOADED');
+    });
+
+    it('has INVALID_INPUT code', () => {
+      expect(SemanticErrorCode.INVALID_INPUT).toBe('INVALID_INPUT');
+    });
+
+    it('has EMBEDDING_FAILED code', () => {
+      expect(SemanticErrorCode.EMBEDDING_FAILED).toBe('EMBEDDING_FAILED');
+    });
+
+    it('has COMPUTATION_FAILED code', () => {
+      expect(SemanticErrorCode.COMPUTATION_FAILED).toBe('COMPUTATION_FAILED');
+    });
+
+    it('has DIMENSION_MISMATCH code', () => {
+      expect(SemanticErrorCode.DIMENSION_MISMATCH).toBe('DIMENSION_MISMATCH');
+    });
+  });
+
+  describe('error behavior', () => {
+    it('can be thrown and caught', () => {
+      const throwError = () => {
+        throw new SemanticError(
+          SemanticErrorCode.INVALID_INPUT,
+          'Test error'
+        );
+      };
+
+      expect(throwError).toThrow(SemanticError);
+      expect(throwError).toThrow('Test error');
+    });
+
+    it('preserves stack trace', () => {
+      const error = new SemanticError(
+        SemanticErrorCode.INVALID_INPUT,
+        'Test error'
+      );
+
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('SemanticError');
+    });
+
+    it('can be checked with instanceof', () => {
+      try {
+        throw new SemanticError(
+          SemanticErrorCode.MODEL_NOT_LOADED,
+          'Model not loaded'
+        );
+      } catch (error) {
+        expect(error instanceof SemanticError).toBe(true);
+        expect(error instanceof Error).toBe(true);
+      }
+    });
+
+    it('code can be used for error handling', () => {
+      const handleError = (error: SemanticError): string => {
+        switch (error.code) {
+          case SemanticErrorCode.MODEL_NOT_LOADED:
+            return 'Please initialize the model first';
+          case SemanticErrorCode.INVALID_INPUT:
+            return 'Please check your input';
+          case SemanticErrorCode.DIMENSION_MISMATCH:
+            return 'Vector dimensions must match';
+          default:
+            return 'An error occurred';
+        }
+      };
+
+      const error1 = new SemanticError(
+        SemanticErrorCode.MODEL_NOT_LOADED,
+        'Not loaded'
+      );
+      const error2 = new SemanticError(
+        SemanticErrorCode.INVALID_INPUT,
+        'Bad input'
+      );
+
+      expect(handleError(error1)).toBe('Please initialize the model first');
+      expect(handleError(error2)).toBe('Please check your input');
+    });
+  });
+});