@pranavraut033/ats-checker 1.0.4 → 1.1.0

package/README.md

@@ -1,6 +1,33 @@
-# ats-checker
+# @pranavraut033/ats-checker
 
-A zero-dependency TypeScript library for evaluating resume compatibility with Applicant Tracking Systems (ATS). It parses resumes and job descriptions, calculates a deterministic score from 0 to 100, and provides actionable feedback to improve match rates.
+[![npm version](https://img.shields.io/npm/v/@pranavraut033/ats-checker.svg)](https://www.npmjs.com/package/@pranavraut033/ats-checker)
+[![npm downloads](https://img.shields.io/npm/dm/@pranavraut033/ats-checker.svg)](https://www.npmjs.com/package/@pranavraut033/ats-checker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/Pranavraut033/ats-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/Pranavraut033/ats-checker/actions/workflows/ci.yml)
+[![Build Status](https://github.com/Pranavraut033/ats-checker/actions/workflows/deploy.yml/badge.svg)](https://github.com/Pranavraut033/ats-checker/actions/workflows/deploy.yml)
+
+Zero-dependency TypeScript library that scores a resume against a job description and explains why — skills coverage, keyword overlap, experience match, and education — with no randomness, no LLM, and no external calls.
+
+**[Live Demo →](https://pranavraut033.github.io/ats-checker/)**  
+**[Docs →](https://pranavraut033.github.io/ats-checker/docs/)**
+
+---
+
+## Features
+
+- **Deterministic** — same input always produces the same score; pin it with `referenceDate` to freeze "Present" date math
+- **Explainable** — breakdown by category (skills / experience / keywords / education) plus matched and missing skill/keyword lists
+- **Configurable** — adjust weights, add skill aliases, define custom penalty rules
+- **Zero dependencies** — core library has no runtime deps; ships ESM + CJS
+- **Built-in profiles** — software engineer, data scientist, product manager out of the box
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+
+---
 
 ## Installation
 
@@ -8,165 +35,188 @@ A zero-dependency TypeScript library for evaluating resume compatibility with Ap
 npm install @pranavraut033/ats-checker
 ```
 
+---
+
 ## Usage
 
 ```typescript
 import { analyzeResume } from "@pranavraut033/ats-checker";
 
 const result = analyzeResume({
-  resumeText: `John Doe
-Software Engineer with 5 years of experience in JavaScript and React.`,
-  jobDescription: `We are looking for a software engineer with JavaScript experience.`
+  resumeText: `
+    Software Engineer with 5 years of experience.
+    Skills: JavaScript, TypeScript, React, Node.js, SQL
+    Experience: Senior Engineer at ExampleCorp (Jan 2020 - Present)
+    Education: B.S. Computer Science
+  `,
+  jobDescription: `
+    Frontend engineer role. Must have React, TypeScript, accessibility best practices.
+    Preferred: GraphQL. 3+ years required. Bachelor's degree required.
+  `,
+  config: { referenceDate: "2026-01-01" }, // freeze clock for reproducible scores
 });
 
-console.log(result.score); // 78
-console.log(result.breakdown.skills); // 85
-console.log(result.suggestions); // ["Add more specific JavaScript frameworks", ...]
+console.log(result.score);            // e.g. 72.45
+console.log(result.matchedSkills);    // ["javascript", "node", "react", "typescript"]
+console.log(result.missingSkills);    // ["accessibility best practices", "graphql"]
+console.log(result.experienceGap);    // 0 (requirement met)
+console.log(result.suggestions);      // ["Add GraphQL to your skills section", ...]
 ```
 
-### LLM (Async) Usage
-
-For AI-enhanced suggestions while keeping scores deterministic, use the async API:
+---
 
-```typescript
-import { analyzeResumeAsync } from "@pranavraut033/ats-checker";
+## Output
 
-const myLLMClient = /* implement LLMClient (OpenAI/Anthropic/local) */;
+`analyzeResume()` returns an `ATSAnalysisResult`:
 
-const result = await analyzeResumeAsync({
-  resumeText: "...",
-  jobDescription: "...",
-  llm: {
-    client: myLLMClient,
-    models: { default: "gpt-4o-mini" },
-    limits: { maxCalls: 3, maxTokensPerCall: 1000, maxTotalTokens: 5000 },
-    enable: { suggestions: true }
-  }
-});
+| Field | Type | Description |
+|---|---|---|
+| `score` | `number` | Overall ATS score 0–100 after rule penalties |
+| `breakdown` | `ATSBreakdown` | Sub-scores: `skills`, `experience`, `keywords`, `education` |
+| `matchedSkills` | `string[]` | Required skills found in the resume |
+| `missingSkills` | `string[]` | Required skills absent from the resume |
+| `matchedKeywords` | `string[]` | JD keywords present in the resume (sorted) |
+| `missingKeywords` | `string[]` | JD keywords absent from the resume (sorted) |
+| `overusedKeywords` | `string[]` | Keywords exceeding density threshold (sorted) |
+| `suggestions` | `string[]` | Deterministic improvement recommendations |
+| `warnings` | `string[]` | Parse warnings and section alerts |
+| `experienceGap` | `number` | Years below JD minimum; `0` when met |
+| `detectedSections` | `string[]` | Resume sections the parser found |
+| `parsedExperienceYears` | `number` | Total years from resume date ranges |
 
-console.log(result.score);        // unchanged by LLM
-console.log(result.suggestions);  // enhanced wording/context
-```
+**Scoring formula:**  
+`score = skills×0.30 + experience×0.30 + keywords×0.25 + education×0.15` → clamped to 0–100 → rule penalties subtracted.
 
-Note: Passing `llm` to `analyzeResume` (sync) will add a warning and skip enhancement. Prefer `analyzeResumeAsync` for LLM features.
+---
 
 ## Configuration
 
-Adjust scoring priorities, define skill synonyms, and add custom rules:
+All options are optional. Pass any subset; `resolveConfig()` fills in defaults.
 
 ```typescript
 const result = analyzeResume({
   resumeText: "...",
   jobDescription: "...",
   config: {
+    // Override scoring weights (auto-normalized to sum to 1)
     weights: { skills: 0.4, experience: 0.3, keywords: 0.2, education: 0.1 },
-    skillAliases: { "javascript": ["js", "ecmascript"] },
+
+    // Additional skill synonyms merged over built-in defaults
+    skillAliases: { javascript: ["js", "ecmascript"] },
+
+    // Industry profile: sets mandatory/optional skills and minExperience
+    profile: {
+      mandatorySkills: ["javascript", "react"],
+      optionalSkills: ["graphql", "docker"],
+      minExperience: 3,
+    },
+
+    // Freeze "Present" end dates for reproducible experience scoring
+    referenceDate: "2026-01-01",
+
+    // Keyword density thresholds
+    keywordDensity: { min: 0.0025, max: 0.04, overusePenalty: 5 },
+
+    // Custom penalty rules
     rules: [
       {
-        id: "min-years",
-        penalty: 5,
-        warning: "Less than 3 years experience",
-        condition: (ctx) => (ctx.resume.experienceYears ?? 0) < 3
+        id: "no-tables",
+        penalty: 10,
+        warning: "Remove tables — ATS parsers often mangle them",
+        condition: (ctx) => ctx.resume.detectedSections.length < 2,
       },
       {
-        id: "require-contact",
-        penalty: 2,
-        warning: "Add phone/email to contact info",
-        condition: (ctx) => !ctx.resume.contactInfo?.phone || !ctx.resume.contactInfo?.email
-      }
-    ]
-  }
+        id: "experience-gap",
+        penalty: 5,
+        warning: "Resume has less than 3 years experience",
+        condition: (ctx) => ctx.resume.totalExperienceYears < 3,
+      },
+    ],
+  },
 });
 ```
 
-See [Configuration](docs/configuration.md) for complete options.
+### Defaults
+
+| Setting | Default |
+|---|---|
+| `weights.skills` | `0.30` |
+| `weights.experience` | `0.30` |
+| `weights.keywords` | `0.25` |
+| `weights.education` | `0.15` |
+| `keywordDensity.min` | `0.0025` |
+| `keywordDensity.max` | `0.04` |
+| `keywordDensity.overusePenalty` | `5` |
+| `allowPartialMatches` | `true` |
+| `referenceDate` | Current date (use explicit ISO string for determinism) |
+
+See [Configuration docs](https://pranavraut033.github.io/ats-checker/docs/configuration/) for all options.
 
-### Configuration Defaults
+---
 
-- Weights: skills 0.3, experience 0.3, keywords 0.25, education 0.15 (normalized)
-- Keyword density: min 0.0025, max 0.04, overusePenalty 5
-- Section penalties: summary 4, experience 10, skills 8, education 6
-- Partial matches: `allowPartialMatches: true`
+## Built-in Skill Aliases
 
-All user config is merged via `resolveConfig()` and weights are normalized to sum to 1.0.
+Common tech synonyms are pre-loaded so `js` matches `javascript`, `k8s` matches `kubernetes`, etc. Extend or override via `config.skillAliases`.
+
+```typescript
+import { defaultSkillAliases } from "@pranavraut033/ats-checker";
+// { javascript: ["js"], node: ["node.js", "nodejs"], typescript: ["ts"], ... }
+```
 
-### Custom Rules
+---
 
-Add penalties/warnings via rule conditions:
+## Built-in Profiles
 
 ```typescript
+import {
+  softwareEngineerProfile,
+  dataScientistProfile,
+  productManagerProfile,
+} from "@pranavraut033/ats-checker";
+
 const result = analyzeResume({
   resumeText: "...",
   jobDescription: "...",
-  config: {
-    rules: [
-      {
-        id: "min-years",
-        penalty: 5,
-        warning: "Less than 3 years experience",
-        condition: (ctx) => (ctx.resume.experienceYears ?? 0) < 3
-      },
-      {
-        id: "require-contact",
-        penalty: 2,
-        warning: "Add phone/email to contact info",
-        condition: (ctx) => !ctx.resume.contactInfo?.phone || !ctx.resume.contactInfo?.email
-      }
-    ]
-  }
+  config: { profile: softwareEngineerProfile },
 });
 ```
-See [Rules Engine](docs/rules.md) for default rules and context fields.
-
-## Features
 
-- Deterministic scoring based on skills, experience, keywords, and education
-- Detects common ATS issues like missing sections or keyword overuse
-- Customizable scoring weights and validation rules
-- Optional LLM integration for enhanced suggestions
-- Includes a web interface for testing (`npm run dev`)
-- [Live Demo](https://pranavraut033.github.io/ats-checker/)
+---
 
-## API
+## LLM Integration (deprecated)
 
-### `analyzeResume(input: AnalyzeResumeInput): ATSAnalysisResult`
+`analyzeResumeAsync` accepts an optional `llm` config that rewrites suggestion text via a caller-supplied LLM client. **This path is deprecated** — scores and breakdowns are never touched by LLM. Prefer calling `analyzeResume` and running your own LLM pass on `result.suggestions` if you want AI-enhanced wording.
 
-Analyzes a resume against a job description.
-
-**Input:**
-- `resumeText: string` - The full text of the resume
-- `jobDescription: string` - The job description text
-- `config?: ATSConfig` - Optional configuration overrides
-
-**Output:**
-- `score: number` - Overall ATS score (0-100)
-- `breakdown: ATSBreakdown` - Component scores
-- `matchedKeywords: string[]` - Keywords found in both
-- `missingKeywords: string[]` - Important keywords not in resume
-- `suggestions: string[]` - Improvement recommendations
-- `warnings: string[]` - Issues detected
+---
 
 ## Development
 
 ```bash
 npm install
-npm run build    # Build to dist/
-npm test         # Run tests
-npm run dev      # Start web UI at http://localhost:3005
+npm run build       # tsup → ESM + CJS in dist/
+npm test            # vitest (single pass)
+npm run type-check  # tsc --noEmit
+npm run dev         # static demo UI at http://localhost:3005
 ```
 
+---
+
 ## Documentation
 
-**Live Docs** (hosted on GitHub Pages):
-- https://Pranavraut033.github.io/ats-checker/docs/
+Full docs at **[pranavraut033.github.io/ats-checker/docs/](https://pranavraut033.github.io/ats-checker/docs/)**
 
-**Local Docs** (in repository):
-- [Configuration Guide](docs/configuration.md)
-- [LLM Integration](docs/llm-integration.md)
-- [Web Interface](docs/ui.md)
 - [Architecture](docs/architecture.md)
+- [Configuration](docs/configuration.md)
+- [Rules Engine](docs/rules.md)
 
-## License
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome.
 
-MIT
+---
+
+## License
 
+MIT © [Pranav Raut](https://github.com/Pranavraut033)

package/dist/index.d.mts

@@ -79,6 +79,13 @@ interface ATSConfig {
     keywordDensity?: KeywordDensityConfig;
     sectionPenalties?: SectionPenaltyConfig;
     allowPartialMatches?: boolean;
+    /**
+     * ISO date string (e.g. "2024-06-01") used as the "today" reference when
+     * computing duration for open-ended date ranges ("Present"/"Current"/"Now").
+     * Omit to use the actual current date (live/production behaviour).
+     * Set to a fixed value in tests or batch processing to guarantee determinism.
+     */
+    referenceDate?: string;
 }
 interface NormalizedWeights extends ATSWeights {
     /** Weights normalized so they sum to 1. */
@@ -92,6 +99,8 @@ interface ResolvedATSConfig {
     keywordDensity: KeywordDensityConfig;
     sectionPenalties: Required<SectionPenaltyConfig>;
     allowPartialMatches: boolean;
+    /** Resolved reference date for "Present" duration calculations. */
+    referenceDate?: Date;
 }
 interface RuleContext {
     resume: ParsedResume;
@@ -224,11 +233,21 @@ interface AnalyzeResumeInput {
 interface ATSAnalysisResult {
     score: number;
     breakdown: ATSBreakdown;
+    /** Skills found in the resume that satisfy JD + profile requirements. */
+    matchedSkills: string[];
+    /** Required skills absent from the resume. */
+    missingSkills: string[];
     matchedKeywords: string[];
     missingKeywords: string[];
     overusedKeywords: string[];
     suggestions: string[];
     warnings: string[];
+    /** Years below the JD's minimum experience requirement; 0 when the requirement is met. */
+    experienceGap: number;
+    /** Resume sections the parser successfully detected (e.g. "summary", "skills"). */
+    detectedSections: string[];
+    /** Total years of experience parsed from the resume's date ranges. */
+    parsedExperienceYears: number;
 }
 
 declare const defaultSkillAliases: SkillAliases;
@@ -277,10 +296,6 @@ declare class LLMManager {
      * Check if features are enabled
      */
     isFeatureEnabled(feature: keyof NonNullable<LLMConfig["enable"]>): boolean;
-    /**
-     * Create a timeout promise
-     */
-    private createTimeout;
     /**
      * Estimate tokens for a call (rough approximation)
      * 1 token ≈ 4 characters average
@@ -475,18 +490,12 @@ declare function safeExtractNumber(obj: unknown, key: string): number | undefine
  */
 declare function analyzeResume(input: AnalyzeResumeInput): ATSAnalysisResult;
 /**
- * Async version: Analyze a resume with full LLM support
- * This version properly handles async LLM calls
+ * @deprecated The LLM layer only rewrites suggestion text and adds non-determinism.
+ * Prefer `analyzeResume` (sync, deterministic) and call your own LLM on the result if needed.
+ * This function will be removed in a future major version.
  *
  * @param input Resume, job description, and optional LLM config
  * @returns Promise<ATSAnalysisResult>
- *
- * @example
- * const result = await analyzeResumeAsync({
- *   resumeText,
- *   jobDescription,
- *   llm: { client, limits: {...}, enable: { suggestions: true } }
- * });
  */
 declare function analyzeResumeAsync(input: AnalyzeResumeInput): Promise<ATSAnalysisResult>;
 

package/dist/index.d.ts

@@ -79,6 +79,13 @@ interface ATSConfig {
     keywordDensity?: KeywordDensityConfig;
     sectionPenalties?: SectionPenaltyConfig;
     allowPartialMatches?: boolean;
+    /**
+     * ISO date string (e.g. "2024-06-01") used as the "today" reference when
+     * computing duration for open-ended date ranges ("Present"/"Current"/"Now").
+     * Omit to use the actual current date (live/production behaviour).
+     * Set to a fixed value in tests or batch processing to guarantee determinism.
+     */
+    referenceDate?: string;
 }
 interface NormalizedWeights extends ATSWeights {
     /** Weights normalized so they sum to 1. */
@@ -92,6 +99,8 @@ interface ResolvedATSConfig {
     keywordDensity: KeywordDensityConfig;
     sectionPenalties: Required<SectionPenaltyConfig>;
     allowPartialMatches: boolean;
+    /** Resolved reference date for "Present" duration calculations. */
+    referenceDate?: Date;
 }
 interface RuleContext {
     resume: ParsedResume;
@@ -224,11 +233,21 @@ interface AnalyzeResumeInput {
 interface ATSAnalysisResult {
     score: number;
     breakdown: ATSBreakdown;
+    /** Skills found in the resume that satisfy JD + profile requirements. */
+    matchedSkills: string[];
+    /** Required skills absent from the resume. */
+    missingSkills: string[];
     matchedKeywords: string[];
     missingKeywords: string[];
     overusedKeywords: string[];
     suggestions: string[];
     warnings: string[];
+    /** Years below the JD's minimum experience requirement; 0 when the requirement is met. */
+    experienceGap: number;
+    /** Resume sections the parser successfully detected (e.g. "summary", "skills"). */
+    detectedSections: string[];
+    /** Total years of experience parsed from the resume's date ranges. */
+    parsedExperienceYears: number;
 }
 
 declare const defaultSkillAliases: SkillAliases;
@@ -277,10 +296,6 @@ declare class LLMManager {
      * Check if features are enabled
      */
     isFeatureEnabled(feature: keyof NonNullable<LLMConfig["enable"]>): boolean;
-    /**
-     * Create a timeout promise
-     */
-    private createTimeout;
     /**
      * Estimate tokens for a call (rough approximation)
      * 1 token ≈ 4 characters average
@@ -475,18 +490,12 @@ declare function safeExtractNumber(obj: unknown, key: string): number | undefine
  */
 declare function analyzeResume(input: AnalyzeResumeInput): ATSAnalysisResult;
 /**
- * Async version: Analyze a resume with full LLM support
- * This version properly handles async LLM calls
+ * @deprecated The LLM layer only rewrites suggestion text and adds non-determinism.
+ * Prefer `analyzeResume` (sync, deterministic) and call your own LLM on the result if needed.
+ * This function will be removed in a future major version.
  *
  * @param input Resume, job description, and optional LLM config
  * @returns Promise<ATSAnalysisResult>
- *
- * @example
- * const result = await analyzeResumeAsync({
- *   resumeText,
- *   jobDescription,
- *   llm: { client, limits: {...}, enable: { suggestions: true } }
- * });
  */
 declare function analyzeResumeAsync(input: AnalyzeResumeInput): Promise<ATSAnalysisResult>;