careerclaw-js 0.11.0

package/dist/matching/scoring.d.ts

@@ -0,0 +1,84 @@
+/**
+ * matching/scoring.ts — Pure per-dimension scoring functions.
+ *
+ * Each dimension function returns a value in [0, 1].
+ * Neutral (0.5) is used when data is missing so absent fields neither
+ * reward nor penalise the composite score.
+ *
+ * compositeScore() uses a multiplicative model:
+ *
+ *   total = sqrt(keyword_score) × qualityBase
+ *
+ * where qualityBase = weighted sum of experience + salary + work_mode.
+ *
+ * This means keyword overlap is a signal multiplier, not just another
+ * additive term. A job with zero keyword overlap scores 0.0 regardless
+ * of how well it matches on salary or work mode — solving the problem
+ * of irrelevant jobs floating to the top on neutral dimension scores.
+ *
+ * sqrt() softens the penalty for partial keyword matches: a job with
+ * 25% keyword overlap gets a signal of 0.5 (not 0.25), so genuine
+ * partial matches are still surfaced meaningfully.
+ *
+ * All functions are pure and stateless — safe to unit test in isolation.
+ */
+import type { NormalizedJob, UserProfile, MatchBreakdown } from "../models.js";
+/**
+ * Score keyword overlap between the user profile and a job posting.
+ *
+ * Profile corpus: skills + target_roles + resume_summary tokens (combined).
+ * Job corpus:     title + description tokens.
+ *
+ * Returns Jaccard-like intersection/union in [0, 1].
+ * Returns 0.0 if either corpus tokenises to empty.
+ */
+export declare function scoreKeyword(profile: UserProfile, job: NormalizedJob): {
+    score: number;
+    matched: string[];
+    gaps: string[];
+};
+/**
+ * Score alignment between user experience years and job requirements.
+ *
+ * - Returns neutral 0.5 if either side has no data.
+ * - Returns 1.0 if the job requires 0 years.
+ * - Clamped linear: user_years / job_years, capped at 1.0.
+ *   Over-qualified candidates are not penalised.
+ */
+export declare function scoreExperience(profile: UserProfile, job: NormalizedJob): number;
+/**
+ * Score alignment between user salary expectations and the job's posted range.
+ *
+ * - Returns neutral 0.5 if either side has no data.
+ * - Returns 1.0 if job minimum meets or exceeds user minimum.
+ * - Proportional score if job pays less, clamped to [0, 1].
+ */
+export declare function scoreSalary(profile: UserProfile, job: NormalizedJob): number;
+/**
+ * Score alignment between user work mode preference and job work mode.
+ *
+ * - Returns 1.0 on exact match.
+ * - Returns 0.5 if either side is null (insufficient data).
+ * - Returns 0.5 if one side is hybrid (partial compatibility).
+ * - Returns 0.0 on hard mismatch (remote vs onsite).
+ */
+export declare function scoreWorkMode(profile: UserProfile, job: NormalizedJob): number;
+/**
+ * Compute the weighted composite score.
+ *
+ * Formula:
+ *   qualityBase = (experience × 0.4) + (salary × 0.3) + (work_mode × 0.3)
+ *   total       = sqrt(keyword) × qualityBase
+ *
+ * The keyword score acts as a signal multiplier:
+ *   - keyword = 0.0 → total = 0.0 always (the "dentist fix")
+ *   - keyword = 1.0 → total = qualityBase
+ *   - keyword = 0.25 → signal = 0.5 (sqrt softens partial-match penalty)
+ */
+export declare function compositeScore(profile: UserProfile, job: NormalizedJob): {
+    total: number;
+    breakdown: MatchBreakdown;
+    matched: string[];
+    gaps: string[];
+};
+//# sourceMappingURL=scoring.d.ts.map

package/dist/matching/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../../src/matching/scoring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAqC/E;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,aAAa,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAmBtD;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,aAAa,GACjB,MAAM,CASR;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,aAAa,GACjB,MAAM,CAUR;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,aAAa,GACjB,MAAM,CAUR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,aAAa,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAoBjF"}

package/dist/matching/scoring.js

@@ -0,0 +1,184 @@
+/**
+ * matching/scoring.ts — Pure per-dimension scoring functions.
+ *
+ * Each dimension function returns a value in [0, 1].
+ * Neutral (0.5) is used when data is missing so absent fields neither
+ * reward nor penalise the composite score.
+ *
+ * compositeScore() uses a multiplicative model:
+ *
+ *   total = sqrt(keyword_score) × qualityBase
+ *
+ * where qualityBase = weighted sum of experience + salary + work_mode.
+ *
+ * This means keyword overlap is a signal multiplier, not just another
+ * additive term. A job with zero keyword overlap scores 0.0 regardless
+ * of how well it matches on salary or work mode — solving the problem
+ * of irrelevant jobs floating to the top on neutral dimension scores.
+ *
+ * sqrt() softens the penalty for partial keyword matches: a job with
+ * 25% keyword overlap gets a signal of 0.5 (not 0.25), so genuine
+ * partial matches are still surfaced meaningfully.
+ *
+ * All functions are pure and stateless — safe to unit test in isolation.
+ */
+import { tokenizeUnique, tokenOverlap, matchedTokens, gapTokens, } from "../core/text-processing.js";
+// ---------------------------------------------------------------------------
+// Weights for the quality dimensions (must sum to 1.0)
+// ---------------------------------------------------------------------------
+/**
+ * Quality dimension weights — applied AFTER the keyword signal multiplier.
+ * These normalise the three metadata dimensions to a [0, 1] quality base.
+ *
+ * Originating weights (additive model):
+ *   experience 20%, salary 15%, work_mode 15%  →  sum = 50%
+ * Normalised to sum to 1.0 for the quality base:
+ *   experience 0.4, salary 0.3, work_mode 0.3
+ */
+const QUALITY_WEIGHTS = {
+    experience: 0.4,
+    salary: 0.3,
+    work_mode: 0.3,
+};
+// Verify weights sum to 1.0 at module load time
+const _weightSum = Object.values(QUALITY_WEIGHTS).reduce((a, b) => a + b, 0);
+if (Math.abs(_weightSum - 1.0) > 1e-9) {
+    throw new Error(`QUALITY_WEIGHTS must sum to 1.0, got ${_weightSum}`);
+}
+// ---------------------------------------------------------------------------
+// Keyword score
+// ---------------------------------------------------------------------------
+/**
+ * Score keyword overlap between the user profile and a job posting.
+ *
+ * Profile corpus: skills + target_roles + resume_summary tokens (combined).
+ * Job corpus:     title + description tokens.
+ *
+ * Returns Jaccard-like intersection/union in [0, 1].
+ * Returns 0.0 if either corpus tokenises to empty.
+ */
+export function scoreKeyword(profile, job) {
+    const profileText = [
+        ...profile.skills,
+        ...profile.target_roles,
+        profile.resume_summary ?? "",
+    ].join(" ");
+    const profileTokens = tokenizeUnique(profileText);
+    const jobTokens = tokenizeUnique(`${job.title} ${job.description}`);
+    if (profileTokens.length === 0 || jobTokens.length === 0) {
+        return { score: 0.0, matched: [], gaps: [] };
+    }
+    return {
+        score: tokenOverlap(profileTokens, jobTokens),
+        matched: matchedTokens(profileTokens, jobTokens),
+        gaps: gapTokens(jobTokens, profileTokens),
+    };
+}
+// ---------------------------------------------------------------------------
+// Experience score
+// ---------------------------------------------------------------------------
+/**
+ * Score alignment between user experience years and job requirements.
+ *
+ * - Returns neutral 0.5 if either side has no data.
+ * - Returns 1.0 if the job requires 0 years.
+ * - Clamped linear: user_years / job_years, capped at 1.0.
+ *   Over-qualified candidates are not penalised.
+ */
+export function scoreExperience(profile, job) {
+    const userYears = profile.experience_years;
+    const jobYears = job.experience_years;
+    if (userYears === null || userYears === undefined)
+        return 0.5;
+    if (jobYears === null || jobYears === undefined)
+        return 0.5;
+    if (jobYears === 0)
+        return 1.0;
+    return Math.min(userYears / jobYears, 1.0);
+}
+// ---------------------------------------------------------------------------
+// Salary score
+// ---------------------------------------------------------------------------
+/**
+ * Score alignment between user salary expectations and the job's posted range.
+ *
+ * - Returns neutral 0.5 if either side has no data.
+ * - Returns 1.0 if job minimum meets or exceeds user minimum.
+ * - Proportional score if job pays less, clamped to [0, 1].
+ */
+export function scoreSalary(profile, job) {
+    const userMin = profile.salary_min;
+    const jobMin = job.salary_min;
+    if (userMin === null || userMin === undefined)
+        return 0.5;
+    if (jobMin === null || jobMin === undefined)
+        return 0.5;
+    if (userMin === 0)
+        return 1.0;
+    if (jobMin >= userMin)
+        return 1.0;
+    return Math.max(jobMin / userMin, 0.0);
+}
+// ---------------------------------------------------------------------------
+// Work mode score
+// ---------------------------------------------------------------------------
+/**
+ * Score alignment between user work mode preference and job work mode.
+ *
+ * - Returns 1.0 on exact match.
+ * - Returns 0.5 if either side is null (insufficient data).
+ * - Returns 0.5 if one side is hybrid (partial compatibility).
+ * - Returns 0.0 on hard mismatch (remote vs onsite).
+ */
+export function scoreWorkMode(profile, job) {
+    const userMode = profile.work_mode;
+    const jobMode = job.work_mode;
+    if (userMode === null || userMode === undefined)
+        return 0.5;
+    if (jobMode === null || jobMode === undefined)
+        return 0.5;
+    if (userMode === jobMode)
+        return 1.0;
+    if (userMode === "hybrid" || jobMode === "hybrid")
+        return 0.5;
+    return 0.0;
+}
+// ---------------------------------------------------------------------------
+// Composite score — multiplicative model
+// ---------------------------------------------------------------------------
+/**
+ * Compute the weighted composite score.
+ *
+ * Formula:
+ *   qualityBase = (experience × 0.4) + (salary × 0.3) + (work_mode × 0.3)
+ *   total       = sqrt(keyword) × qualityBase
+ *
+ * The keyword score acts as a signal multiplier:
+ *   - keyword = 0.0 → total = 0.0 always (the "dentist fix")
+ *   - keyword = 1.0 → total = qualityBase
+ *   - keyword = 0.25 → signal = 0.5 (sqrt softens partial-match penalty)
+ */
+export function compositeScore(profile, job) {
+    const kw = scoreKeyword(profile, job);
+    const experience = scoreExperience(profile, job);
+    const salary = scoreSalary(profile, job);
+    const work_mode = scoreWorkMode(profile, job);
+    const qualityBase = experience * QUALITY_WEIGHTS.experience +
+        salary * QUALITY_WEIGHTS.salary +
+        work_mode * QUALITY_WEIGHTS.work_mode;
+    const signal = Math.sqrt(kw.score);
+    const total = roundScore(signal * qualityBase);
+    return {
+        total,
+        breakdown: { keyword: kw.score, experience, salary, work_mode },
+        matched: kw.matched,
+        gaps: kw.gaps,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function roundScore(n) {
+    return Math.round(n * 10_000) / 10_000;
+}
+//# sourceMappingURL=scoring.js.map

package/dist/matching/scoring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.js","sourceRoot":"","sources":["../../src/matching/scoring.ts"],"names":[],"mappings":"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"}

package/dist/models.d.ts

@@ -0,0 +1,221 @@
+/**
+ * models.ts — Canonical data schemas for CareerClaw.
+ *
+ * These types are the single source of truth for all data flowing through
+ * the pipeline. JSON serialisation formats are intentionally kept identical
+ * to the Python careerclaw package so that profile.json, tracking.json, and
+ * runs.jsonl files remain compatible between the two implementations.
+ */
+/** Application lifecycle states, persisted as lowercase strings in JSON. */
+export type ApplicationStatus = "saved" | "applied" | "interviewing" | "rejected" | "offer";
+/** Work-mode preference. Matches the values accepted in profile.json. */
+export type WorkMode = "remote" | "hybrid" | "onsite" | "any";
+/** Canonical source identifiers for job listings. */
+export type JobSource = "remoteok" | "hackernews" | "unknown";
+/**
+ * A normalised job record produced by any adapter.
+ *
+ * `job_id` is a stable SHA-256 hex digest of the canonical URL (or
+ * company+title when no URL is available).  It is used as the primary key
+ * in tracking.json and for deduplication across sources and runs.
+ */
+export interface NormalizedJob {
+    /** Stable hash-based identifier. */
+    job_id: string;
+    title: string;
+    company: string;
+    /** Raw location string from the source ("Remote", "NYC", etc.). */
+    location: string;
+    description: string;
+    /** Canonical URL — empty string when unavailable. */
+    url: string;
+    source: JobSource;
+    /** Minimum salary in annualised USD, or null when not stated. */
+    salary_min: number | null;
+    /** Maximum salary in annualised USD, or null when not stated. */
+    salary_max: number | null;
+    /** Normalised work mode inferred from job text, or null when ambiguous. */
+    work_mode: WorkMode | null;
+    /** Required years of experience inferred from job text, or null. */
+    experience_years: number | null;
+    /** ISO-8601 UTC timestamp of when the job was posted, or null. */
+    posted_at: string | null;
+    /** ISO-8601 UTC timestamp of when this record was fetched. */
+    fetched_at: string;
+}
+/**
+ * User profile loaded from `.careerclaw/profile.json`.
+ *
+ * All fields are optional so that partial profiles (e.g. profiles created
+ * incrementally via the OpenClaw agent wizard) are still valid at runtime.
+ * The briefing pipeline degrades gracefully when fields are missing.
+ */
+export interface UserProfile {
+    skills: string[];
+    target_roles: string[];
+    /** Total years of professional experience. */
+    experience_years: number | null;
+    work_mode: WorkMode | null;
+    /** Short free-text resume summary used for keyword extraction. */
+    resume_summary: string | null;
+    /** City / region string used for location scoring. */
+    location: string | null;
+    /** Minimum acceptable annual salary in USD. */
+    salary_min: number | null;
+}
+/**
+ * A single tracked application in `.careerclaw/tracking.json`.
+ *
+ * Keyed by `job_id` in the JSON file.  All timestamps are ISO-8601 UTC.
+ */
+export interface TrackingEntry {
+    job_id: string;
+    status: ApplicationStatus;
+    /** Snapshot of the job title at time of saving. */
+    title: string;
+    /** Snapshot of the company name at time of saving. */
+    company: string;
+    url: string;
+    source: JobSource;
+    /** ISO-8601 UTC timestamp when the entry was first saved. */
+    saved_at: string;
+    /** ISO-8601 UTC timestamp when the application was submitted, or null. */
+    applied_at: string | null;
+    /** ISO-8601 UTC timestamp when the entry was last updated. */
+    updated_at: string;
+    /** ISO-8601 UTC timestamp when this job was last seen in a briefing run. */
+    last_seen_at: string | null;
+    notes: string | null;
+}
+/**
+ * A single run record appended to `.careerclaw/runs.jsonl`.
+ *
+ * Each line in the JSONL file is one serialised BriefingRun.
+ */
+export interface BriefingRun {
+    /** Random UUID v4 identifying this run. */
+    run_id: string;
+    /** ISO-8601 UTC timestamp when the run started. */
+    run_at: string;
+    /** Whether this was a dry-run (no writes to disk). */
+    dry_run: boolean;
+    /** Total jobs fetched across all sources. */
+    jobs_fetched: number;
+    /** Jobs that passed deduplication and were considered for ranking. */
+    jobs_ranked: number;
+    /** Top-k jobs returned by the engine. */
+    jobs_matched: number;
+    /** Source breakdown, e.g. { remoteok: 12, hackernews: 7 }. */
+    sources: Partial<Record<JobSource, number>>;
+    /** Wall-clock duration in milliseconds for each pipeline stage. */
+    timings: {
+        fetch_ms: number | null;
+        rank_ms: number | null;
+        draft_ms: number | null;
+        persist_ms: number | null;
+    };
+    /** careerclaw-js package version that produced this run. */
+    version: string;
+}
+/**
+ * Per-dimension score breakdown produced by the matching engine.
+ * All values are in [0, 1].
+ */
+export interface MatchBreakdown {
+    /** Raw Jaccard-like keyword overlap score in [0, 1]. */
+    keyword: number;
+    experience: number;
+    salary: number;
+    work_mode: number;
+}
+/**
+ * A ranked job with its composite score and explanation.
+ */
+export interface ScoredJob {
+    job: NormalizedJob;
+    /** Weighted composite score in [0, 1]. */
+    score: number;
+    breakdown: MatchBreakdown;
+    /** Human-readable explanation tokens (matched keywords etc.). */
+    matched_keywords: string[];
+    /** Skills/requirements in the job not present in the user profile. */
+    gap_keywords: string[];
+}
+/**
+ * Structured requirements extracted from a job description.
+ * Used as the job corpus for gap analysis.
+ */
+export interface JobRequirements {
+    keywords: string[];
+    phrases: string[];
+}
+/**
+ * Section-aware keyword extraction from a resume / profile.
+ * Schema is JSON-compatible with the Python careerclaw output.
+ */
+export interface ResumeIntelligence {
+    extracted_keywords: string[];
+    extracted_phrases: string[];
+    keyword_stream: string[];
+    phrase_stream: string[];
+    impact_signals: string[];
+    keyword_weights: Record<string, number>;
+    phrase_weights: Record<string, number>;
+    source: 'summary_only' | 'resume_text' | 'skills_injected';
+}
+/**
+ * Result of gapAnalysis() — fit score and matched/gap keyword lists.
+ */
+export interface GapAnalysisResult {
+    fit_score: number;
+    fit_score_unweighted: number;
+    signals: {
+        keywords: string[];
+        phrases: string[];
+    };
+    gaps: {
+        keywords: string[];
+        phrases: string[];
+    };
+    summary: {
+        top_signals: {
+            keywords: string[];
+            phrases: string[];
+        };
+        top_gaps: {
+            keywords: string[];
+            phrases: string[];
+        };
+    };
+}
+export interface OutreachDraft {
+    job_id: string;
+    subject: string;
+    body: string;
+    /** True when the draft was produced by LLM enhancement (Pro tier). */
+    llm_enhanced: boolean;
+}
+/** Returns an ISO-8601 UTC timestamp string for the current moment. */
+export declare function utcNow(): string;
+/** Returns a default empty UserProfile. */
+export declare function emptyProfile(): UserProfile;
+/**
+ * The complete output of a single briefing run.
+ * This is the stable JSON schema consumed by OpenClaw/ClawHub agents.
+ */
+export interface BriefingResult {
+    /** The BriefingRun record that was (or would be) appended to runs.jsonl. */
+    run: BriefingRun;
+    /** Top-K scored jobs produced by the ranking engine. */
+    matches: ScoredJob[];
+    /** One OutreachDraft per match, in the same order as matches[]. */
+    drafts: OutreachDraft[];
+    /** Counts from upsertEntries() — always accurate even in dry-run. */
+    tracking: {
+        created: number;
+        already_present: number;
+    };
+    /** Whether this was a dry run (no files written). */
+    dry_run: boolean;
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"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"}

package/dist/models.js

@@ -0,0 +1,28 @@
+/**
+ * models.ts — Canonical data schemas for CareerClaw.
+ *
+ * These types are the single source of truth for all data flowing through
+ * the pipeline. JSON serialisation formats are intentionally kept identical
+ * to the Python careerclaw package so that profile.json, tracking.json, and
+ * runs.jsonl files remain compatible between the two implementations.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Returns an ISO-8601 UTC timestamp string for the current moment. */
+export function utcNow() {
+    return new Date().toISOString();
+}
+/** Returns a default empty UserProfile. */
+export function emptyProfile() {
+    return {
+        skills: [],
+        target_roles: [],
+        experience_years: null,
+        work_mode: null,
+        resume_summary: null,
+        location: null,
+        salary_min: null,
+    };
+}
+//# sourceMappingURL=models.js.map

package/dist/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyNH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,uEAAuE;AACvE,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,YAAY;IAC1B,OAAO;QACL,MAAM,EAAE,EAAE;QACV,YAAY,EAAE,EAAE;QAChB,gBAAgB,EAAE,IAAI;QACtB,SAAS,EAAE,IAAI;QACf,cAAc,EAAE,IAAI;QACpB,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC"}

package/dist/requirements.d.ts

@@ -0,0 +1,22 @@
+/**
+ * requirements.ts — Job requirements extractor.
+ *
+ * Extracts a structured keyword + phrase corpus from a job posting's
+ * title and description. This corpus is the "job side" input for
+ * gap analysis (Phase 5) and is distinct from the full tokenisation
+ * used by the matching engine — here we want raw coverage, not scoring.
+ *
+ * No heuristics beyond tokenisation: STOPWORDS filtering already removes
+ * boilerplate (apply, candidate, competitive, etc.) so the resulting
+ * keyword list reflects genuine technical and role signals.
+ */
+import type { NormalizedJob, JobRequirements } from "./models.js";
+/**
+ * Extract requirements corpus from a job posting.
+ *
+ * Combines title and description into a single text corpus, then
+ * tokenises and extracts bigram/trigram phrases. Both lists are
+ * deduplicated (insertion order preserved).
+ */
+export declare function extractJobRequirements(job: NormalizedJob): JobRequirements;
+//# sourceMappingURL=requirements.d.ts.map

package/dist/requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOlE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAK1E"}

package/dist/requirements.js

@@ -0,0 +1,30 @@
+/**
+ * requirements.ts — Job requirements extractor.
+ *
+ * Extracts a structured keyword + phrase corpus from a job posting's
+ * title and description. This corpus is the "job side" input for
+ * gap analysis (Phase 5) and is distinct from the full tokenisation
+ * used by the matching engine — here we want raw coverage, not scoring.
+ *
+ * No heuristics beyond tokenisation: STOPWORDS filtering already removes
+ * boilerplate (apply, candidate, competitive, etc.) so the resulting
+ * keyword list reflects genuine technical and role signals.
+ */
+import { tokenizeUnique, extractPhrasesFromText } from "./core/text-processing.js";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extract requirements corpus from a job posting.
+ *
+ * Combines title and description into a single text corpus, then
+ * tokenises and extracts bigram/trigram phrases. Both lists are
+ * deduplicated (insertion order preserved).
+ */
+export function extractJobRequirements(job) {
+    const text = `${job.title} ${job.description}`;
+    const keywords = tokenizeUnique(text);
+    const phrases = extractPhrasesFromText(text);
+    return { keywords, phrases };
+}
+//# sourceMappingURL=requirements.js.map

package/dist/requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.js","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAkB;IACvD,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC"}

package/dist/resume-intel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * resume-intel.ts — Section-aware resume intelligence builder.
+ *
+ * `buildResumeIntelligence()` extracts a weighted keyword/phrase corpus
+ * from multiple resume/profile inputs. Each source has a section weight
+ * (from SECTION_WEIGHTS) that determines how important its tokens are
+ * for gap analysis.
+ *
+ * Key design from PR-E: UserProfile.skills are injected as a synthetic
+ * "skills" section at weight 1.0 — the highest weight. This prevents
+ * skills the user explicitly listed from appearing as gaps.
+ *
+ * Output schema is JSON-compatible with Python careerclaw so
+ * `.careerclaw/resume_intel.json` files are portable across
+ * implementations.
+ */
+import type { ResumeIntelligence } from "./models.js";
+export interface ResumeIntelligenceParams {
+    /** Short free-text summary from UserProfile.resume_summary. */
+    resume_summary: string;
+    /** Full resume text from resume.txt or PDF extraction (optional). */
+    resume_text?: string;
+    /** UserProfile.skills — injected as a synthetic skills section (PR-E fix). */
+    skills?: string[];
+    /** UserProfile.target_roles — injected at summary weight. */
+    target_roles?: string[];
+}
+/**
+ * Build section-aware resume intelligence from available inputs.
+ *
+ * Sections processed (highest weight first):
+ *   1. skills        (weight 1.0)  — UserProfile.skills list
+ *   2. summary       (weight 0.8)  — resume_summary + target_roles
+ *   3. experience    (weight 0.6)  — resume_text (if provided)
+ *
+ * For each keyword, the final keyword_weight is the maximum weight
+ * across all sections in which it appeared.
+ */
+export declare function buildResumeIntelligence(params: ResumeIntelligenceParams): ResumeIntelligence;
+//# sourceMappingURL=resume-intel.d.ts.map

package/dist/resume-intel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-intel.d.ts","sourceRoot":"","sources":["../src/resume-intel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAWtD,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,wBAAwB,GAC/B,kBAAkB,CA8FpB"}