jd-skill-gap.mjs
Rama main · réplica de lectura del repositorio original.
#!/usr/bin/env node
/**
* jd-skill-gap.mjs — Zero-LLM JD skill-gap checker.
*
* Extracts an explicit skill/requirement list from a JD (regex-based, no LLM
* call — see extractJdSkills()), then classifies each one against cv.md into
* three buckets so a CV can be tailored honestly instead of guessed at:
*
* existing — already a named skill in cv.md's Skills section
* supportedByResume — not a named skill, but appears in prose elsewhere in cv.md
* gap — JD requires it, cv.md has no trace of it at all
* (nothing is ever auto-added — this tool only classifies and reports)
*
* Design note: the three-way classification (existing / supportedByResume / gap)
* is inspired by the skill-verification pattern in srbhr/Resume-Matcher
* (Apache-2.0) — specifically their four-way verify_skill_target_plan() split.
* This is an independent reimplementation, not a code port: different language,
* zero LLM calls, and folded down to three buckets because career-ops never
* auto-adds a claim to cv.md either way (their jd_added/unsupported distinction
* only matters if a tool is allowed to add something automatically).
*
* Usage:
* node jd-skill-gap.mjs jds/acme.md
* node jd-skill-gap.mjs jds/acme.md --summary
* node jd-skill-gap.mjs --self-test
*/
import { readFileSync, existsSync } from 'fs';
import { canonicalize, extractSkills, SKILL_PATTERN } from './skill-extract.mjs';
import { isMainModule } from './lib/is-main-module.mjs';
import { join } from 'path';
import { getCareerOpsRoot } from './path-resolver.mjs';
import { normalizePandocLine, toPlainText } from './lib/cv-markdown.mjs';
import { collapseMarkdownLinks } from './verify-cv-facts.mjs';
// ── Config ──────────────────────────────────────────────────────────
// From the data root, not the cwd. cv.md is a Source-of-Truth Boundary primary
// file and lives wherever CAREER_OPS_ROOT / CAREER_OPS_DATA_DIR / the
// .career-ops-data marker points; a bare relative path resolves against
// whatever directory the process was started in.
//
// Everything this script reports is a comparison against that file, so without
// it there is nothing to say at all. The error below therefore has to serve two
// different users at once: one who never wrote a cv.md, and one who has one
// sitting outside the data root this resolver just looked in. Naming only one
// of them sends the other to the wrong fix.
const CV_PATH = join(getCareerOpsRoot(), 'cv.md');
// ── JD skill extraction (regex, no LLM) ─────────────────────────────
//
// Looks for lines/phrases under common JD requirement headers and comma/
// bullet-separated skill lists. Deliberately conservative: under-extracting
// (missing a skill) is recoverable by the user reading the JD themselves;
// over-extracting noise into "required skills" is not — it would misreport
// gaps that aren't real.
// Qualified requirement headings (#6255), kept apart so scanJd() can tell a
// line matched by one of them from the older requirement headings.
const QUALIFIED_REQUIREMENT_ARMS = [
// The ^ anchor means the keyword has to be the heading's first word, so
// a qualified noun heading — Amazon's "Basic Qualifications", Google's
// "Minimum Qualifications", "Role Qualifications", "Key Requirements" —
// matched nothing and the JD reported no-requirements-section (#6255).
// The qualifier is a closed list, not "any words": an open prefix would
// turn a prose line such as "Gather and document requirements" into a
// heading and open a block in the middle of the responsibilities.
// The lookahead also requires the keyword to END the heading (or be
// followed by ":" / "("): without it, a bare requirement line such as
// "Technical requirements include Python and Kubernetes" read as a
// heading and its skills were dropped. Closing heading markers
// ("## Basic Qualifications ##", "【Basic Qualifications】") still end it.
'(?:(?:basic|minimum|key|core|job|role|position|technical|essential|desired|desirable|additional|mandatory|general|specific|candidate|professional|education(?:al)?)\\s+){1,2}(?:requirement|qualification)(?=s?[\\s#\u3011]*(?:[:\uFF1A(\uFF08]|$))',
// US public-sector postings title the block "Knowledge, Skills, and
// Abilities" (KSAs), "Experience, Skills, and Abilities", or both joined
// by a slash: "Knowledge/Experience, Skills, and Abilities" (#6255).
// Same end-of-heading lookahead, for the same prose-line reason.
'(?:(?:knowledge|experience|education)(?:\\s*\\/\\s*(?:knowledge|experience|education))?,?\\s+)?skills,?\\s+(?:and|&)\\s+abilit(?:y|ies)(?=[\\s#\u3011]*(?:[:\uFF1A(\uFF08]|$))',
];
const QUALIFIED_REQUIREMENT_HEADER_RE = new RegExp(
'^#{0,6}\\s*\u3010?\\s*(?:' + QUALIFIED_REQUIREMENT_ARMS.join('|') + ')',
'im'
);
// Real postings rarely use the word "Requirements". The literal-only list
// missed the phrasings most modern ATS boards actually ship ("What we're
// looking for", "Who you are", "You may be a good fit if", "You have"), so a
// JD could yield zero skills - which reads identically to "no gaps found" and
// is the more dangerous of the two failure modes this file warns about.
//
// CJK characters are \W (non-word), so the s?\b suffix that works for ASCII
// terms would always fail after a Chinese heading: \b asserts between \w and
// \W, and after a CJK char the following whitespace / colon / newline is also
// \W, so no boundary fires. The fix is a separate alternation arm for CJK
// terms that drops s?\b; both arms share the same ^#{0,6}\s* prefix.
//
// The prefix itself stays #{0,6} — it is NOT widened to also swallow `*`/`_`.
// A bolded heading with no markdown hash ("**What We're Looking For**") is
// handled instead by stripping `**`/`__` pairs from the line before testing
// it against this pattern (see stripBoldMarkers() and its call site in
// scanJd(), #4273). Widening the prefix character class was the first thing
// tried here and it regressed a real, common shape: an asterisk-BULLET whose
// text happens to start with a keyword — "* Required: Python and
// Kubernetes" — would have its leading `*` consumed as a heading marker,
// misclassifying the bullet itself as a new heading (and dropping the
// skills on that exact line, since a heading match short-circuits before
// bullet extraction runs). Stripping only doubled `**`/`__` markers — never
// a single `*`/`_` — leaves a literal bullet character untouched, since a
// real bullet is one asterisk, not two.
const REQUIREMENT_HEADER_RE = new RegExp(
'^#{0,6}\\s*\u3010?\\s*(?:(?:' + [
'required', 'requirements', 'qualifications', 'must[- ]have', 'preferred', 'nice[- ]to[- ]have',
// (?:'|’)?\s*re|\s+are (not just (?:'|’)?\s*re): the contracted-only form
// matched "we're"/"we re" but not the equally common uncontracted "we are"
// (#4273 — the Netflix posting that surfaced this used the uncontracted,
// bolded form of this exact heading).
"what\\s+we(?:(?:'|’)?\\s*re|\\s+are)\\s+looking\\s+for",
"what\\s+you(?:(?:'|’)ll|\\s+will)?\\s+bring",
'who\\s+you\\s+are',
'about\\s+you',
'your\\s+(?:background|experience|profile)',
'you\\s+(?:may|might|could)\\s+be\\s+a\\s+good\\s+fit',
// Ashby's default template ships a bare "YOU HAVE:" heading (no markdown
// hashes - already allowed by the ^#{0,6} prefix). Without this the whole
// requirements block is invisible even though the bullets under it are
// perfectly well formed.
"you(?:(?:'|’)ll|\\s+will)?\\s+have",
// Postings that phrase must-have/nice-to-have as full sentences rather
// than noun headings.
"it(?:'|’)?s\\s+important\\s+to\\s+us\\s+that\\s+you\\s+have",
'it\\s+would\\s+be\\s+great\\s+if\\s+you\\s+ha(?:ve|d)',
'ideal\\s+candidate',
'skills\\s+(?:and|&)\\s+experience',
...QUALIFIED_REQUIREMENT_ARMS,
].join('|') + ')s?\\b|(?:' + [
// Spanish (es-419 / es-ES) requirement headers. A Spanish-language
// posting's requirements block is invisible to the English list above, so
// every Spanish JD read as "no-requirements-section" — the same gap the
// zh-TW / zh-CN entries below close for Chinese postings. `modes/es/`
// makes the Spanish market a supported one.
'requisitos',
'requisitos?\\s+(?:del\\s+puesto|de\\s+la\\s+empresa|del\\s+equipo|principales|m\\u00ednimos)',
'requerimientos',
'requerimientos?\\s+(?:del\\s+puesto|espec\\u00edficos|generales)',
'calificaciones',
'calificaciones?\\s+(?:requeridas|necesarias)',
'qu[eé]\\s+buscamos',
'lo\\s+que\\s+buscamos',
'lo\\s+que\\s+necesitas',
'lo\\s+que\\s+esperamos',
'perfil\\s+(?:del\\s+cargo|de\\s+la\\s+empresa|requerido|ideal)',
'conocimientos',
'conocimientos?\\s+(?:requeridos|necesarios)',
'habilidades',
'habilidades?\\s+(?:requeridas|necesarias)',
'competencias',
'competencias?\\s+(?:requeridas|necesarias)',
'para\\s+el\\s+puesto',
].join('|') + ')\\b|(?:' + [
// zh-TW / zh-CN requirement headers.
// 104 / 1111 / CakeResume / Yourator all use variants of these headings.
'\u61C9\u5FB5\u689D\u4EF6', // 應徵條件
'\u8CC7\u683C\u689D\u4EF6', // 資格條件
'\u8077\u52D9\u9700\u6C42', // 職務需求
'\u689D\u4EF6\u8981\u6C42', // 條件要求
'\u4EFB\u8077\u8CC7\u683C', // 任職資格
'\u5FC5\u8981\u689D\u4EF6', // 必要條件
'\u57FA\u672C\u8981\u6C42', // 基本要求 (same code points in zh-TW and zh-CN)
'\u8077\u4F4D\u8981\u6C42', // 職位要求
// zh-CN (Simplified). The entries above use Traditional code points
// (職 U+8077, 資 U+8CC7, 條 U+689D, 項 U+9805), so a Simplified posting
// (职 U+804C, 资 U+8D44, 条 U+6761, 项 U+9879) never matched them.
'\u804C\u4F4D\u8981\u6C42', // 职位要求
'\u5C97\u4F4D\u8981\u6C42', // 岗位要求
'\u5C97\u4F4D\u57FA\u672C\u8981\u6C42', // 岗位基本要求
'\u4EFB\u804C\u8981\u6C42', // 任职要求
'\u4EFB\u804C\u8D44\u683C', // 任职资格
'\u6761\u4EF6\u8981\u6C42', // 条件要求
// preferred / nice-to-have
'\u52A0\u5206\u9805\u76EE', // 加分項目
'\u52A0\u5206\u689D\u4EF6', // 加分條件
'\u52A0\u5206\u9879', // 加分项 (zh-CN)
].join('|') + ')).*$',
'im'
);
// Headers that end a requirements block even when the posting uses no markdown
// heading levels. Without this the block stayed open to end-of-file and swept
// the benefits list into "required skills" - turning perks like "401k",
// "Equity" and "Carrot" into reported skill gaps.
//
// Same #{0,6} prefix, same reason for leaving it unwidened, as
// REQUIREMENT_HEADER_RE above: a bolded "**Benefits**" with no markdown hash
// is handled by stripBoldMarkers() before this pattern ever sees the line,
// not by letting the prefix itself swallow `*`/`_` (#4273).
const NON_REQUIREMENT_HEADER_RE = new RegExp(
'^#{0,6}\\s*\u3010?\\s*(?:(?:' + [
// Responsibilities. The negative lookahead keeps "You will have" on the
// requirements side — this list is tested BEFORE REQUIREMENT_HEADER_RE in
// scanJd(), so without it a "You will have:" heading would close a block
// instead of opening one. Bare "YOU WILL" must close: the fallback that
// ends a block on a new heading only fires for markdown headings (#{1,6}),
// so an unhashed responsibilities heading left the block open and scored
// its duties as required skills.
'you\\s+will(?!\\s+have)',
'benefits?', 'perks?', 'benefits\\s+and\\s+perks', 'compensation', 'salary', 'pay\\s+range',
'what\\s+we\\s+offer', 'why\\s+(?:join|work|this\\s+role)',
'about\\s+(?:us|the\\s+company|the\\s+team|the\\s+role)',
'how\\s+(?:and\\s+where\\s+)?we\\s+work',
'equal\\s+opportunity', 'eeo', 'diversity',
'interview\\s+process', 'how\\s+to\\s+apply', 'to\\s+apply',
'our\\s+(?:stack|process|values|mission)',
// Spanish (es-419 / es-ES) closing headers. Without them a Spanish
// posting's "Beneficios" block stays open and its perks are scored as
// required skills — the same failure the English closers prevent.
'beneficios?', 'funciones?', 'responsabilidades?',
'lo\\s+que\\s+ofrecemos', 'qu[eé]\\s+ofrecemos', 'nuestro\\s+ofrecimiento',
'acerca\\s+de\\s+nosotros', 'acerca\\s+de\\s+la\\s+empresa',
'c[oó]mo\\s+postular', 'postulaci[oó]n', 'proceso\\s+de\\s+selecci[oó]n',
'etapas\\s+del\\s+proceso',
].join('|') + ')\\b|(?:' + [
// zh-TW / zh-CN closing headers — drops \b for the same CJK reason.
'\u5DE5\u4F5C\u5167\u5BB9', // 工作內容
'\u5DE5\u4F5C\u8077\u8CAC', // 工作職責
'\u8077\u8CAC\u7BC4\u758A', // 職責範疇
'\u798F\u5229', // 福利
'\u85AA\u8CC7', // 薪資
'\u85AA\u916C', // 薪酬 (zh-CN)
'\u516C\u53F8\u4ECB\u7D39', // 公司介紹
'\u95DC\u65BC\u6211\u5011', // 關於我們
'\u61C9\u5FB5\u65B9\u5F0F', // 應徵方式
'\u5982\u4F55\u61C9\u5FB5', // 如何應徵
// zh-CN (Simplified) closing headers.
'\u5DE5\u4F5C\u5185\u5BB9', // 工作内容
'\u5DE5\u4F5C\u804C\u8D23', // 工作职责
'\u5C97\u4F4D\u804C\u8D23', // 岗位职责
'\u804C\u4F4D\u63CF\u8FF0', // 职位描述
'\u85AA\u8D44', // 薪资
'\u516C\u53F8\u4ECB\u7ECD', // 公司介绍
'\u5173\u4E8E\u6211\u4EEC', // 关于我们
].join('|') + ')).*$',
'im'
);
// `\r?$` is required, not cosmetic: JS treats \r as a line terminator, so `.`
// cannot consume it and a bare `$` never matches on a CRLF-split line.
//
// Numbered items count as list items too. Chinese postings (and many others)
// number their requirements instead of bulleting them: "1、", "1．", "1)",
// "（1）", "①". An ASCII "1." or "1)" needs whitespace after it, so a figure
// such as "3.5+ years" is not read as item 3.
const BULLET_LINE_RE = /^\s*(?:[-*•]|\d{1,2}(?:[.)]\s|[、．）])|[(（]\d{1,2}[)）]|[\u2460-\u2473])\s*(.+)\r?$/;
// Strip markdown STRONG-emphasis markers (`**text**` / `__text__`) so a
// bolded heading with no `#` at all — "**What We're Looking For**" — still
// reaches REQUIREMENT_HEADER_RE / NON_REQUIREMENT_HEADER_RE's own `#{0,6}`
// prefix as if the bold wrapper were never there (#4273).
//
// Only doubled markers: a single `*`/`_` is left completely alone, on
// purpose. `*` is also how a plain markdown bullet starts (BULLET_LINE_RE),
// and a bullet whose text happens to start with a keyword — "* Required:
// Python and Kubernetes" — must stay a bullet, not become a misdetected
// heading that swallows its own line's skills before bullet extraction ever
// runs. `**` (two characters) can never be a single-asterisk bullet marker,
// so this global-replace has no bullet-collision case to worry about.
function stripBoldMarkers(line) {
return line.replace(/\*\*|__/g, '');
}
// A conservative skill-token extractor: pulls comma/slash/and-separated
// technical-looking tokens out of a requirement bullet, rather than treating
// the whole bullet as one skill string (JD bullets are often full sentences).
//
// Trailing boundary: \b fails at symbol edges (\bC\+\+\b needs a word char
// AFTER the +), so C++/C#/F# would never match standalone — same bug and fix
// as upskill.mjs's SKILL_PATTERN, where (?!\w) is equivalent to \b for
// word-char edges and correct for symbol edges. Because the char class here
// is greedy and contains ".", the last token char is additionally pinned to
// a word char / # / + so a sentence-ending period is never swallowed into
// the token ("Docker." still extracts as "Docker"). The leading \b stays:
// tokens start with [A-Z], a word char, where \b and (?<!\w) are equivalent.
const SKILL_TOKEN_RE = /\b([A-Z][A-Za-z0-9+.#]{0,29}[A-Za-z0-9+#](?:\.[a-z]{2,4})?)(?!\w)/g;
// Deliberately broad: this list exists specifically to stop generic
// capitalized nouns/adjectives from JD bullets (e.g. "Bachelor's degree
// required", "3+ years of experience") from being misreported as missing
// "skills" — the exact failure mode this file's design note warns against.
const STOPWORDS = new Set([
'the', 'and', 'for', 'with', 'you', 'your', 'our', 'this', 'that', 'these', 'those',
'must', 'able', 'ability', 'strong', 'excellent', 'proven', 'a', 'an', 'or', 'in', 'of', 'to', 'as', 'is', 'are',
// degree / education boilerplate
'bachelor', 'bachelors', 'master', 'masters', 'degree', 'diploma', 'certification', 'certificate',
// experience / seniority boilerplate
'experience', 'years', 'year', 'senior', 'junior', 'entry', 'level', 'minimum', 'preferred', 'required',
// generic sentence-starters that show up capitalized at the start of a bullet
'candidates', 'candidate', 'applicants', 'applicant', 'ideal', 'successful',
'knowledge', 'understanding', 'familiarity', 'exposure', 'background',
'skills', 'skill', 'communication', 'team', 'teams', 'work', 'working',
// Capitalized bullet-openers that read as skills but describe the candidate's
// disposition, not a technology ("Deep fluency in…", "Interest in…").
'deep', 'interest', 'genuine', 'solid', 'comfortable', 'passion', 'passionate',
'track', 'record', 'real', 'bonus', 'plus', 'hands', 'proficiency', 'fluency',
'expertise', 'demonstrated', 'extensive', 'practical', 'good', 'great', 'clear',
// Capitalized words that name a field or an artifact, not a skill a CV can
// list: "AI tools", "build a Demo" (#5292). Specific AI skills (RAG, LLMs,
// Prompt Engineering, ...) are still read through the shared vocabulary.
'ai', 'demo',
]);
// A known skill that is more than one word (#5292). SKILL_TOKEN_RE reads one
// word at a time, so "Prompt Engineering" came out as two gaps, "Prompt" and
// "Engineering", neither of which canonicalize() knows, and a CV that lists
// "Prompt Engineering" could never satisfy them. The shared vocabulary already
// has these phrases, so they are matched from SKILL_PATTERN before the
// single-word pass rather than through a second tokenizer here.
//
// Only phrases that start with a capital letter, the same conservative rule as
// SKILL_TOKEN_RE: a lowercase bullet still extracts nothing (see
// diagnoseExtraction()). The JD's own spelling is kept, as for single words;
// classifySkillGaps() canonicalizes it.
function isPhraseMatch(match) {
return /\s/.test(match) && /^[A-Z]/.test(match);
}
// Requirement text written in Chinese is never a candidate: SKILL_TOKEN_RE and
// the shared vocabulary are both Latin-script. A requirement line that still
// has this many Han characters once its skill tokens are taken out is recorded
// as not read, so the output can say the check covered it only partly
// (#5292). Four, not one: short connectives such as 熟悉, 精通 and 优先 sit
// around Latin skill names in fully read lines, and are two characters each.
const UNREAD_HAN_MIN = 4;
const HAN_RE = /\p{Script=Han}/gu;
// The Set scanJd() collects skills into, plus the requirement lines it could
// not read. A Set subclass, so addSkillTokens() keeps its (text, skills)
// signature at every call site.
class SkillCollector extends Set {
constructor() {
super();
this.unreadLines = [];
}
}
/**
* Scan a JD once, returning both the extracted skills and whether a
* requirement-style section was ever opened.
*
* `sawRequirementSection` is what lets the caller tell apart the two very
* different reasons an extraction can come back empty: "I never found a
* requirements section, so I checked nothing" versus "I checked one and
* recognized none of its terms". Both print as zero skills, and the first is
* the one that silently skips the gate in modes/pdf.md Step 4.
*
* Kept as one state machine with extractJdSkills deliberately: a second copy of
* the block-open/block-close logic would drift from this one, which is the exact
* failure the shared skill-extract.mjs module was introduced to end.
*
* @param {string} jdText
* @returns {{skills: string[], sawRequirementSection: boolean}}
*/
function scanJd(jdText) {
const lines = jdText.split('\n');
const skills = new SkillCollector();
let inRequirementsBlock = false;
let sawRequirementSection = false;
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
// Header-classification only, never bullet extraction below: a bolded
// heading ("**Benefits**") must match these two regexes as if the bold
// wrapper weren't there, but a bolded SKILL inside a bullet
// ("- **Docker** and **Kubernetes**") already extracts fine as-is via
// SKILL_TOKEN_RE, which skips right over `*` since it isn't in the
// token's character class — stripping there would be a no-op at best
// (#4273).
const headerLine = stripBoldMarkers(line);
// Checked before the requirement test so a heading that satisfies both
// (e.g. "Why this role") closes the block rather than reopening it.
if (NON_REQUIREMENT_HEADER_RE.test(headerLine)) {
inRequirementsBlock = false;
continue;
}
if (REQUIREMENT_HEADER_RE.test(headerLine)) {
inRequirementsBlock = true;
sawRequirementSection = true;
// "Requirements: SQL; dbt; Tableau" puts the whole list on the header
// line, with no bullets under it. A separator is required so a sentence
// such as "About you: Curious and kind" is not read as a list.
// The full-width colon and the CJK separators (、，；) count the same as
// their ASCII forms: "任职要求：Python、Docker".
const colon = headerLine.search(/[:：]/);
let inline = colon === -1 ? '' : headerLine.slice(colon + 1);
// A qualified heading may carry its list in parentheses instead:
// "Basic Qualifications (Python and Kubernetes)", full-width included.
if (!inline && QUALIFIED_REQUIREMENT_HEADER_RE.test(headerLine)) {
const paren = headerLine.search(/[(（]/);
if (paren !== -1) inline = headerLine.slice(paren + 1);
}
// A qualified heading with no separator ("Technical requirements:
// Python and Kubernetes") was a requirement line before #6255 made it a
// heading, so its known skills are kept — vocabulary names only. Every
// other heading keeps the #5173 rule: a sentence after the colon ("About
// you: Curious about Kubernetes.") is not a list.
if (/[;,、，；]/.test(inline)) addSkillTokens(inline, skills);
else if (QUALIFIED_REQUIREMENT_HEADER_RE.test(headerLine)) {
for (const skill of extractSkills(inline)) skills.add(skill);
}
continue;
}
if (inRequirementsBlock && line.trim() === '') continue;
if (inRequirementsBlock && /^#{1,6}\s/.test(line) && !REQUIREMENT_HEADER_RE.test(headerLine)) {
inRequirementsBlock = false;
}
if (!inRequirementsBlock) continue;
const bulletMatch = BULLET_LINE_RE.exec(line);
if (bulletMatch) {
addSkillTokens(bulletMatch[1], skills);
continue;
}
// Text copied from a rendered posting page loses its list markers, so each
// requirement arrives as a bare line. A bare line with blank lines on both
// sides is a heading neither regex knows ("Core values"), and it closes the
// block. A bare line next to other lines is a requirement.
const isolated = (lines[i - 1] ?? '').trim() === '' && (lines[i + 1] ?? '').trim() === '';
if (isolated) {
inRequirementsBlock = false;
continue;
}
// A bare line is a sentence, so its first word is capitalized as grammar
// ("Possess a curiosity"). Drop it unless the vocabulary knows it as a skill.
const opener = /^\s*([A-Z][a-z]+)\s+[a-z]/.exec(line);
const unknownOpener = opener && extractSkills(opener[1]).size === 0;
addSkillTokens(unknownOpener ? line.slice(opener[0].length - 1) : line, skills);
}
return { skills: [...skills], sawRequirementSection, unreadLines: skills.unreadLines };
}
function addSkillTokens(text, skills) {
// Known multi-word skills first, each blanked out so the single-word pass
// below cannot also split it into fragments. Both passes are then added in
// the order the JD wrote them.
const found = [];
let rest = text;
for (const m of text.matchAll(SKILL_PATTERN)) {
if (!isPhraseMatch(m[0])) continue;
found.push({ index: m.index, token: m[0] });
rest = rest.slice(0, m.index) + ' '.repeat(m[0].length) + rest.slice(m.index + m[0].length);
}
let m;
SKILL_TOKEN_RE.lastIndex = 0;
while ((m = SKILL_TOKEN_RE.exec(rest)) !== null) {
const token = m[1].trim();
if (!STOPWORDS.has(token.toLowerCase()) && token.length > 1) {
found.push({ index: m.index, token });
}
}
for (const { token } of found.sort((a, b) => a.index - b.index)) skills.add(token);
if (skills.unreadLines) {
const hanLeft = (rest.replace(SKILL_TOKEN_RE, ' ').match(HAN_RE) || []).length;
if (hanLeft >= UNREAD_HAN_MIN) skills.unreadLines.push(text.trim());
}
}
/**
* Extract candidate skill tokens from a JD's requirement-style sections.
* @param {string} jdText
* @returns {string[]}
*/
function extractJdSkills(jdText) {
return scanJd(jdText).skills;
}
/**
* Explain an empty extraction, so "found nothing to check" stops reading as
* "checked and found no gaps".
*
* Returns null when the run is conclusive (at least one skill was classified).
* Otherwise returns a reason code and a message for the user.
*
* The second reason deliberately says "no skill candidates were extracted"
* rather than blaming the vocabulary. Extraction can come back empty for
* reasons that have nothing to do with dictionary coverage: SKILL_TOKEN_RE only
* captures uppercase-leading tokens, so a lowercase bullet like
* "- python and kubernetes experience" yields nothing even though
* skill-extract.mjs knows both names. STOPWORDS can also empty a bullet. All the
* caller can honestly be told is that nothing was classified.
*
* There is deliberately no minimum-length test here. That would need a
* character cutoff, and this repo has no JD corpus to calibrate one against:
* `jds/` is user-layer and gitignored, and the only JD-shaped files in the tree
* (`evals/fixtures/*.txt`) are recorded score-summary stubs that all extract
* zero skills already. A made-up cutoff would fire on those and still not
* describe why a real JD came back empty. The structural question — was there a
* requirements section to scan at all — separates the causes without a constant.
*
* @param {string} jdText
* @param {string[]} jdSkills
* @returns {{reason: string, message: string}|null}
*/
function diagnoseExtraction(jdText, jdSkills) {
if (jdSkills.length > 0) return null;
if (jdText.trim() === '') {
return {
reason: 'empty-jd',
message: 'The JD file is empty, so nothing was checked.',
};
}
if (!scanJd(jdText).sawRequirementSection) {
return {
reason: 'no-requirements-section',
message:
'No requirements section was recognized in this JD, so no text was scanned for skills. ' +
'This is not the same as "no gaps": the check did not run. Read the JD yourself before drafting.',
};
}
return {
reason: 'no-skill-candidates',
message:
'A requirements section was found and scanned, but no skill candidates were extracted from it. ' +
'This is not the same as "no gaps": nothing was classified. Read the JD yourself before drafting.',
};
}
/**
* Say when a run classified skills but could not read part of the
* requirements. diagnoseExtraction() covers the empty run; this covers the
* partial one, which otherwise prints as complete: a Chinese requirements
* block whose bullets mention two Latin tool names yields those two and
* silently drops every requirement written in Chinese (#5292).
*
* Non-blocking, like lowConfidence: the classified buckets are still right
* for what they contain.
*
* @param {string} jdText
* @returns {{reason: string, unreadLines: string[], message: string}|null}
*/
function diagnoseCoverage(jdText) {
const { unreadLines } = scanJd(jdText);
if (unreadLines.length === 0) return null;
return {
reason: 'untokenized-cjk',
unreadLines,
message:
`${unreadLines.length} requirement line(s) contain Chinese text that this check cannot read, ` +
'so requirements written in Chinese were not classified. The buckets cover only the Latin-script ' +
'skill names. Read those lines yourself before drafting.',
};
}
// ── Word-boundary text matching (same technique as Resume-Matcher's
// _skill_mentioned_in_text — prevents "Java" matching inside "JavaScript") ──
/**
* Word-boundary, case-insensitive check for whether a skill token appears in text.
* @param {string} skill
* @param {string} text
* @returns {boolean}
*/
function skillMentionedInText(skill, text) {
const escaped = skill.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const re = new RegExp(`(?<![\\w])${escaped}(?![\\w])`, 'i');
return re.test(text);
}
// ── Skills-section split ─────────────────────────────────────────────
//
// Line-scan instead of a single regex: JS regex has no `\Z`-style
// end-of-string anchor (unlike Python, where this pattern was designed),
// so a lookahead built on `\Z` either fails to match a trailing Skills
// section at all or matches a literal "Z" character later in the text.
// Scanning line-by-line for the next heading avoids the anchor entirely.
const ANY_HEADING_RE = /^#{1,6}\s/;
// Which headings open a named skills section (#4879). The heading is read
// through lib/cv-markdown.mjs first, so `## **[Skills]{.smallcaps}**` counts.
// "Skills" or "Competencies" anywhere in the heading counts at any level
// ("Technical Skills", "Core Competencies", the title build-cv-html.mjs
// renders for the competency grid). "Tools" / "Technologies" / "Tech Stack" only count on a
// level-1 or level-2 heading: at level 3 they would also match an employer
// such as "### Acme Technologies — Remote" and promote that job's prose into
// named skills.
//
// The Spanish words are the ones a Spanish cv.md actually uses: "Aptitudes y
// Habilidades" and "Competencias Técnicas". Without them a Spanish cv.md had
// no named-skills section at all, so every skill it listed was reported as a
// gap — the check's own "already in Skills section" bucket stayed empty.
const SKILLS_WORD_RE = /\b(?:skills|competenc(?:y|ies)|aptitudes|habilidades|competencias)\b/i;
const TOOLS_WORD_RE = /\b(?:tools|technologies|tech\s+stack)\b/i;
function isSkillsHeading(line) {
// `\s*` rather than `\s+` keeps the historical `#Skills` (no space) form.
const m = String(line).match(/^(#{1,6})(?!#)\s*(.+?)\s*$/);
if (!m) return false;
const text = toPlainText(normalizePandocLine(m[2]).replace(/\s*\{[^}]*\}\s*$/, ''));
return SKILLS_WORD_RE.test(text) || (m[1].length <= 2 && TOOLS_WORD_RE.test(text));
}
/**
* Split cv.md into its named skills sections (if any) and the remaining
* prose, without relying on a Python-style end-of-string regex anchor. Every
* skills heading contributes its section, up to the next heading of any
* level, so a CV with both "## Core Skills" and "## Technical Platforms &
* Tools" counts both.
* @param {string} cvText
* @returns {{namedSkillsText: string, proseText: string}}
*/
function splitSkillsSection(cvText) {
const named = [];
const prose = [];
let inSkills = false;
for (const line of cvText.split('\n')) {
const skillsHeading = isSkillsHeading(line);
if (skillsHeading || ANY_HEADING_RE.test(line)) {
inSkills = skillsHeading;
// A skills heading itself belongs to neither side.
if (!skillsHeading) prose.push(line);
continue;
}
(inSkills ? named : prose).push(line);
}
return { namedSkillsText: named.join('\n'), proseText: prose.join('\n') };
}
// ── Classification ───────────────────────────────────────────────────
/**
* Classify each JD skill against cv.md into existing / supportedByResume / gap.
* @param {string[]} jdSkills
* @param {string} cvText
* @returns {{existing: string[], supportedByResume: string[], gap: string[]}}
*/
function classifySkillGaps(jdSkills, cvText) {
// Only what a reader of the CV sees is evidence: a link's text, not its target,
// the rule verify-cv-facts.mjs applies (#6606). "[infrastructure modules](
// https://github.com/jane/terraform-modules)" says nothing about Terraform, but
// its URL put Terraform in supportedByResume, which modes/pdf.md offers to the
// tailored CV's Skills section.
const { namedSkillsText, proseText } = splitSkillsSection(collapseMarkdownLinks(cvText));
// Canonical skill sets present in each CV region. Folding BOTH the JD token
// and the CV text through skill-extract.mjs's canonicalize() is what closes
// the alias gap this file was reported for (#1896): a CV that writes "k8s"
// and a JD that says "Kubernetes" resolve to the same canonical name instead
// of being reported as a false gap. This is the shared tokenizer upskill.mjs
// already promised — three parallel copies used to disagree.
const namedCanon = extractSkills(namedSkillsText);
const proseCanon = extractSkills(proseText);
const existing = [];
const supportedByResume = [];
const gap = [];
for (const skill of jdSkills) {
const canon = canonicalize(skill);
// "Known" = skill-extract reads this token as its own canonical skill. For
// known skills the canonical-set lookup is authoritative and alias-safe.
// Unknown/free tokens canonicalize to themselves and fall through to the
// word-boundary heuristic below, which is byte-for-byte the prior behavior
// — jd-skill-gap keeps its own heuristics for free tokens (#1896 answer 2).
// A known skill must not reach that heuristic: it matches the JD's spelling
// anywhere, including the prose skill-extract declines to count ("go the
// extra mile", "a safe environment", "Fine-tuning the funnel"). Containing
// a skill is not being one: "React.js" extracts as React, never as itself,
// so it stays a free token and the heuristic still finds it in a CV.
const known = extractSkills(skill).has(canon);
if (known && namedCanon.has(canon)) {
existing.push(skill);
} else if (known && proseCanon.has(canon)) {
supportedByResume.push(skill);
} else if (!known && skillMentionedInText(skill, namedSkillsText)) {
existing.push(skill);
} else if (!known && skillMentionedInText(skill, proseText)) {
supportedByResume.push(skill);
} else {
gap.push(skill);
}
}
return { existing, supportedByResume, gap };
}
// ── Exports (for test-all.mjs and other consumers) ───────────────────
export { extractJdSkills, skillMentionedInText, classifySkillGaps, diagnoseExtraction, diagnoseCoverage };
// ── CLI ──────────────────────────────────────────────────────────────
const args = process.argv.slice(2);
const summaryMode = args.includes('--summary');
const selfTestMode = args.includes('--self-test');
const jdPathArg = args.find(a => !a.startsWith('--'));
function runSelfTest() {
let passed = 0, failed = 0;
const eq = (label, actual, expected) => {
const a = JSON.stringify(actual), e = JSON.stringify(expected);
if (a === e) {
passed++;
} else {
failed++;
console.log(` FAIL: ${label}\n expected: ${e}\n actual: ${a}`);
}
};
const fakeJd = `
# Senior Engineer — Fabrikam Inc.
## Requirements
- Python, FastAPI, PostgreSQL
- Experience with Kubernetes
- Strong communication skills
`;
const fakeCv = `
# Skills
Python, PostgreSQL, Docker
# Experience
Deployed services onto Kubernetes clusters and wrote FastAPI endpoints for internal tools.
`;
const jdSkills = extractJdSkills(fakeJd);
eq('extracts Python from requirements bullet', jdSkills.includes('Python'), true);
eq('extracts Kubernetes from a separate bullet', jdSkills.includes('Kubernetes'), true);
eq('does not extract stopword "Strong"', jdSkills.includes('Strong'), false);
const result = classifySkillGaps(['Python', 'PostgreSQL', 'Kubernetes', 'FastAPI', 'Rust'], fakeCv);
eq('Python classified as existing (named skill)', result.existing.includes('Python'), true);
eq('Kubernetes classified as supportedByResume (prose only)', result.supportedByResume.includes('Kubernetes'), true);
eq('FastAPI classified as supportedByResume (prose only)', result.supportedByResume.includes('FastAPI'), true);
eq('Rust classified as a real gap', result.gap.includes('Rust'), true);
// Regression: a Skills section that is the LAST section in cv.md, with no
// trailing heading after it. The original draft used a Python-style `\Z`
// end-of-string anchor, which JS regex has no equivalent for — it either
// failed to match this case at all, or matched a literal "Z" character
// later in the text. This fixture is that exact shape (Skills is last,
// and the text contains a "Z"-adjacent word to catch the literal-match
// failure mode too).
const trailingSkillsCv = `
# Experience
Worked with Rust in a prior role.
# Skills
Python, Docker, Zookeeper
`;
const trailingResult = classifySkillGaps(['Python', 'Zookeeper'], trailingSkillsCv);
eq(
'trailing Skills section (last in doc, contains a "Z" word) is still captured as named skills',
trailingResult.existing.includes('Zookeeper'),
true
);
// The cv.md side of the six-level widening: SKILLS_HEADING_RE and
// ANY_HEADING_RE also stopped at four. An h5 "Skills" heading meant no
// named section was found at all (everything downgraded to
// supportedByResume), and once it IS found, the h6 heading after it must
// still close the section - otherwise Experience prose leaks into the
// named skills and upgrades to existing. One assert per regex: reverting
// SKILLS_HEADING_RE to #{1,4} turns the first red, reverting
// ANY_HEADING_RE alone turns the second red.
const deepHeadingCv = [
'# Resume', '',
'##### Skills', 'Python, Docker, PostgreSQL', '',
'###### Experience', 'Deployed Kubernetes clusters for internal tools.',
].join('\n');
const deepCvResult = classifySkillGaps(['Python', 'Docker', 'PostgreSQL', 'Kubernetes'], deepHeadingCv);
eq('an h5 Skills heading is recognized as the named section', deepCvResult.existing.includes('Python'), true);
eq('the named section stops at the h6 heading (Kubernetes stays prose)', deepCvResult.existing.includes('Kubernetes'), false);
eq('prose under the h6 still classifies as supportedByResume', deepCvResult.supportedByResume.includes('Kubernetes'), true);
// Pandoc-flavored and differently named skills headings (#4879). The
// issue's repro: skills under "## **[Technical Platforms & Tools]{.smallcaps}**"
// were reported as resume prose, so the existing bucket was always empty.
const pandocSkillsCv = [
'# Jane Example', '',
'## **[Technical Platforms & Tools]{.smallcaps}**', '',
'- Cloud: AWS, Kubernetes, Terraform', '',
'## **[Professional Experience]{.smallcaps}**', '',
'### **Acme Technologies** --- New York, NY', '',
'Migrated the PostgreSQL fleet.',
].join('\n');
const pandocSkillsResult = classifySkillGaps(['AWS', 'Kubernetes', 'Terraform', 'PostgreSQL'], pandocSkillsCv);
eq('a bold + span "Technical Platforms & Tools" heading is a named skills section',
pandocSkillsResult.existing.sort(), ['AWS', 'Kubernetes', 'Terraform']);
eq('a level-3 employer named "... Technologies" is not a skills section',
pandocSkillsResult.supportedByResume, ['PostgreSQL']);
for (const heading of ['## Technical Skills', '## **[Skills]{.smallcaps}**', '### Core Skills', '## Technologies', '# Tech Stack', '## Skills {#skills}']) {
eq(`"${heading}" opens a named skills section`,
classifySkillGaps(['Python'], `${heading}\nPython\n`).existing, ['Python']);
}
for (const heading of ['## Core Competencies', '## Competencies', '## Skills & Competencies', '### Key Competency Areas']) {
eq(`"${heading}" opens a named skills section`,
classifySkillGaps(['Python'], `${heading}\nPython\n`).existing, ['Python']);
}
eq('a "Competition Wins" heading is not a skills section',
classifySkillGaps(['Python'], '## Competition Wins\nPython\n').existing, []);
const twoSectionsCv = '## Skills\nPython\n\n## Experience\nUsed Docker daily.\n\n## Tools\nTerraform\n';
const twoSectionsResult = classifySkillGaps(['Python', 'Terraform', 'Docker'], twoSectionsCv);
eq('every skills section counts, not just the first', twoSectionsResult.existing.sort(), ['Python', 'Terraform']);
eq('prose between two skills sections stays prose', twoSectionsResult.supportedByResume, ['Docker']);
// Regression: requirement headings that are full sentences or bare
// uppercase rather than the noun forms ("Requirements", "Qualifications").
// Each of these silently yielded ZERO skills, which is indistinguishable
// from "no gaps found" — the failure mode this file's header warns about.
const headerVariants = [
['bare uppercase "YOU HAVE:" (Ashby default template)', 'YOU HAVE:'],
['"You\'ll have"', "You'll have:"],
['"You will have"', 'You Will Have:'],
['"You might be a good fit if you:"', 'You Might Be a Good Fit If You:'],
['"You could be a good fit if you:"', 'You Could Be a Good Fit If You:'],
['"It\'s Important To Us That You Have"', "## It's Important To Us That You Have"],
['"It Would Be Great if You Had"', '## It Would Be Great if You Had'],
];
for (const [label, heading] of headerVariants) {
const jd = `# Role\n\n${heading}\n- Hands-on experience with React, TypeScript and AWS\n`;
const skills = extractJdSkills(jd);
eq(`${label} opens a requirements block`, skills.includes('React'), true);
}
// Guard the other direction: the responsibilities heading "You will" must NOT
// open a requirements block. It reads as a near-miss for "you will have", and
// treating duties as requirements is exactly the over-extraction this file
// calls unrecoverable.
const responsibilitiesJd = `# Role\n\nYOU WILL\n- Ship Kubernetes manifests for the platform team\n`;
eq(
'"YOU WILL" (responsibilities) does not open a requirements block',
extractJdSkills(responsibilitiesJd).includes('Kubernetes'),
false
);
// The assertion above only proves YOU WILL cannot OPEN a block. Closing is
// the case that actually bites: postings routinely list requirements first
// and duties second, and the block-ending fallback in scanJd() fires only on
// markdown headings (#{1,6}) — so a bare responsibilities heading left the
// block open and reported every duty as a missing skill.
const dutiesAfterRequirementsJd = [
'# Role', '', 'YOU HAVE:', '- Experience with Python', '',
'YOU WILL', '- Ship Kubernetes manifests', '- Operate Terraform modules', '',
].join('\n');
const dutiesSkills = extractJdSkills(dutiesAfterRequirementsJd);
eq('requirements before a bare YOU WILL are still extracted', dutiesSkills.includes('Python'), true);
eq('bare "YOU WILL" closes an open requirements block (Kubernetes)', dutiesSkills.includes('Kubernetes'), false);
eq('bare "YOU WILL" closes an open requirements block (Terraform)', dutiesSkills.includes('Terraform'), false);
// Guard the lookahead: "You will have" must still reach REQUIREMENT_HEADER_RE
// even though NON_REQUIREMENT_HEADER_RE is tested first in scanJd().
eq(
'"You will have" opens a block despite the YOU WILL exclusion',
extractJdSkills('# Role\n\nYou Will Have:\n- Experience with Kubernetes\n').includes('Kubernetes'),
true
);
// Markdown defines six heading levels, and the block-ending fallback only
// recognized four (CodeRabbit, reviewing #2176). A posting pasted out of a
// deeply nested doc - or converted from HTML, where an ATS wraps sections in
// h5/h6 - kept the requirements block open across its own next heading, so
// everything below it scored as a required skill.
const deepHeadingJd = [
'##### Requirements', '- Experience with Python', '',
'##### Benefits', '- Equity and a Carrot subscription', '',
'###### About Us', '- We use Kubernetes internally for our own platform',
].join('\n');
const deepSkills = extractJdSkills(deepHeadingJd);
eq('an h5 requirements heading is recognized', deepSkills.includes('Python'), true);
eq('an h5 heading closes the block (Equity)', deepSkills.includes('Equity'), false);
eq('an h6 heading stays closed (Kubernetes)', deepSkills.includes('Kubernetes'), false);
// Regression: generic JD boilerplate must not be misreported as a skill gap.
const boilerplateJd = `
# Role
## Requirements
- Bachelor's degree required
- Experience with cross-functional teams (5+ years)
- Communication skills and Ability to self-organize
`;
// The asserted words are capitalized in the fixture on purpose:
// SKILL_TOKEN_RE only captures uppercase-leading tokens, so a lowercase
// "experience" would never become a candidate and the assertion would
// pass without exercising the STOPWORDS filter at all.
const boilerplateSkills = extractJdSkills(boilerplateJd);
eq('does not extract "Bachelor" as a skill', boilerplateSkills.includes('Bachelor'), false);
eq('does not extract "Experience" as a skill', boilerplateSkills.includes('Experience'), false);
eq('does not extract "Communication" as a skill', boilerplateSkills.includes('Communication'), false);
eq('does not extract "Ability" as a skill', boilerplateSkills.includes('Ability'), false);
// Regression: tokens ending in a symbol (C#, C++, F#). The original trailing
// \b needs a word char AFTER the symbol, so these never matched standalone —
// same bug upskill.mjs's SKILL_PATTERN fixed with a (?!\w) lookahead. The
// sentence-ending "Docker." assertion guards the other edge of the fix: the
// greedy char class contains ".", so the lookahead alone would swallow the
// trailing period into the token.
const symbolEdgeJd = `
# Role
## Requirements
- C#, C++ or F# for backend services
- Familiarity with Docker.
`;
const symbolEdgeSkills = extractJdSkills(symbolEdgeJd);
eq('extracts C# standalone (symbol-edge boundary)', symbolEdgeSkills.includes('C#'), true);
eq('extracts C++ standalone (symbol-edge boundary)', symbolEdgeSkills.includes('C++'), true);
eq('extracts F# standalone (symbol-edge boundary)', symbolEdgeSkills.includes('F#'), true);
eq('sentence-ending token stays clean ("Docker", not "Docker.")', symbolEdgeSkills.includes('Docker'), true);
eq('trailing period is not swallowed into the token', symbolEdgeSkills.includes('Docker.'), false);
// Regression: most real postings never write the word "Requirements". The
// literal-only header list matched none of these, so extraction returned an
// empty list - indistinguishable from "this JD has no skill gaps", which is
// the failure mode that silently skips the whole check.
for (const header of [
"What we're looking for",
'What you will bring',
'Who you are',
'About you',
'You may be a good fit if',
]) {
const jd = `# Role\n\n${header}\n- Experience with Kubernetes and Terraform\n`;
const found = extractJdSkills(jd);
eq(`header "${header}" opens a requirements block`, found.includes('Kubernetes'), true);
}
// Regression: the block only closed on a markdown heading, so a posting whose
// benefits section is plain text kept the block open to end-of-file and
// reported perks as missing skills.
const perksJd = `
# Role
## Requirements
- Experience with Kubernetes
Benefits and Perks (US Only)
- Competitive Equity and Healthcare
- Carrot fertility benefits
`;
const perksSkills = extractJdSkills(perksJd);
eq('requirement skill still extracted before the perks block', perksSkills.includes('Kubernetes'), true);
eq('benefit "Equity" is not reported as a skill', perksSkills.includes('Equity'), false);
eq('benefit "Healthcare" is not reported as a skill', perksSkills.includes('Healthcare'), false);
eq('benefit "Carrot" is not reported as a skill', perksSkills.includes('Carrot'), false);
// Regression: capitalized bullet-openers that describe disposition rather
// than technology were surfacing as gaps ("Deep fluency in…", "Interest in…").
const dispositionJd = `
# Role
## Requirements
- Deep fluency in TypeScript
- Interest in documentation as infrastructure
`;
const dispositionSkills = extractJdSkills(dispositionJd);
eq('real skill still extracted alongside a disposition opener', dispositionSkills.includes('TypeScript'), true);
eq('does not extract "Deep" as a skill', dispositionSkills.includes('Deep'), false);
eq('does not extract "Interest" as a skill', dispositionSkills.includes('Interest'), false);
// Regression (#2540): a JD saved with CRLF line endings extracted zero skills.
// JS treats \r as a line terminator, so `.` cannot consume it and the bare `$`
// in BULLET_LINE_RE (no `m` flag) never matched — every requirement bullet
// failed the test and the run returned an empty list, which reads exactly like
// "no gaps" instead of erroring. Parity between the two line endings is the
// property that was broken, so both variants are built explicitly: with
// core.autocrlf the template literal below is already CRLF in a Windows
// checkout, and an unnormalized fixture would compare CRLF against CRLF and
// pass on the broken regex.
const lineEndingJd = `
# Role
## Requirements
- Python, FastAPI, PostgreSQL
- Experience with Kubernetes
`;
const lfSkills = extractJdSkills(lineEndingJd.replace(/\r\n/g, '\n'));
const crlfSkills = extractJdSkills(lineEndingJd.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n'));
eq('CRLF JD extracts the same skills as the LF JD', crlfSkills, lfSkills);
eq('CRLF JD extracts a non-zero number of skills', crlfSkills.length > 0, true);
const lfClassification = classifySkillGaps(lfSkills, fakeCv);
const crlfClassification = classifySkillGaps(crlfSkills, fakeCv);
eq(
'CRLF JD produces the same classification as the LF JD',
JSON.stringify(crlfClassification),
JSON.stringify(lfClassification)
);
// Regression (#1896): the reported bug. A CV alias and a JD's canonical name
// must not read as a gap. Before the shared skill-extract canonicalization,
// classify compared the two literally — "k8s" in the CV vs "Kubernetes" in
// the JD — and reported Kubernetes as a false gap. canonicalize() now folds
// both to "Kubernetes" so it resolves to the region the CV actually uses it.
const aliasCv = `
# Skills
Python, k8s, Postgres
# Experience
Built data pipelines with golang microservices.
`;
const aliasResult = classifySkillGaps(['Kubernetes', 'PostgreSQL', 'Go', 'Rust'], aliasCv);
eq('CV "k8s" satisfies JD "Kubernetes" (named section, not a false gap)', aliasResult.existing.includes('Kubernetes'), true);
eq('CV "Postgres" satisfies JD "PostgreSQL" (named section)', aliasResult.existing.includes('PostgreSQL'), true);
eq('CV prose "golang" satisfies JD "Go" (supportedByResume)', aliasResult.supportedByResume.includes('Go'), true);
eq('genuinely-absent Rust is still a real gap', aliasResult.gap.includes('Rust'), true);
// Regression (#1896, answer 2): unknown/free tokens keep the prior
// word-boundary behavior — canonicalize passes them through unchanged, so a
// JD token the shared module does not know still matches (or not) exactly as
// before, byte-for-byte.
const freeTokenCv = `
# Skills
Python, Fabrikam-SDK
# Experience
Maintained the internal Fabrikam-SDK build.
`;
const freeResult = classifySkillGaps(['Fabrikam-SDK', 'Contoso-Cloud'], freeTokenCv);
eq('unknown token present in CV still matches (word-boundary fallback preserved)', freeResult.existing.includes('Fabrikam-SDK'), true);
eq('unknown token absent from CV is still a real gap', freeResult.gap.includes('Contoso-Cloud'), true);
// Regression: a known skill is decided by the canonical sets alone. Falling
// through to the word-boundary search matched the JD's spelling in prose that
// skill-extract declines to count, so a marketing CV "fine-tuning the funnel"
// read as support for an ML requirement, and Go and SAFe had the same hole.
const everydayCv = `
# Skills
HubSpot, Google Ads
# Experience
Fine-tuning the funnel to lift ROAS. Willing to go the extra mile; a safe pair of hands.
`;
const everydayResult = classifySkillGaps(['Fine-tuning', 'Go', 'SAFe'], everydayCv);
eq('CV prose "Fine-tuning the funnel" leaves JD "Fine-tuning" a gap', everydayResult.gap.includes('Fine-tuning'), true);
eq('CV prose "go the extra mile" leaves JD "Go" a gap', everydayResult.gap.includes('Go'), true);
eq('CV prose "a safe pair of hands" leaves JD "SAFe" a gap', everydayResult.gap.includes('SAFe'), true);
const mlCv = `
# Skills
PyTorch, Fine-tuning, RAG
# Experience
Shipped a support assistant on Llama 3.
`;
eq('a Skills entry "Fine-tuning" still satisfies JD "Fine-tuning"', classifySkillGaps(['Fine-tuning'], mlCv).existing, ['Fine-tuning']);
// The edge of "known": a token that only contains a skill is not that skill.
// "React.js" extracts as React, so the canonical sets never hold "React.js";
// counting it as known left a CV that lists it with a false gap.
const reactJdSkills = extractJdSkills('## Requirements\n- React.js and TypeScript\n');
eq('the JD tokenizer yields "React.js" as one token', reactJdSkills, ['React.js', 'TypeScript']);
eq(
'JD "React.js" is satisfied by a Skills entry "React.js"',
classifySkillGaps(reactJdSkills, '# Skills\nReact.js, TypeScript\n').existing,
['React.js', 'TypeScript']
);
// Regression (#2278): a JD the extractor cannot read returns zero skills, and
// the three buckets then print exactly like "checked, no gaps found".
// modes/pdf.md Step 4 uses this output as a gate, so the two cases have to be
// distinguishable. diagnoseExtraction() is what makes the empty case loud.
// Conclusive run: at least one skill classified, so no warning.
eq(
'a JD that yields skills is diagnosed as conclusive (no warning)',
diagnoseExtraction(fakeJd, extractJdSkills(fakeJd)),
null
);
// The reported shape: a real, substantial JD whose sections use none of the
// recognized requirement headers. Nothing is ever scanned, so zero skills come
// back — not because the candidate has no gaps, but because the check no-opped.
const unreadableJd = `
# Enablement Content Manager
## What you'll do
- Own the ADDIE and SAM design lifecycle for field-facing curriculum
- Build role-based learning paths, certifications and accreditation programs
- Produce e-learning modules, talk tracks, playbooks and demo flows
- Administer the LMS and design assessments and validation programs
`;
eq('unreadable JD extracts zero skills', extractJdSkills(unreadableJd).length, 0);
eq(
'zero skills with no requirements section is reported as no-requirements-section',
diagnoseExtraction(unreadableJd, extractJdSkills(unreadableJd)).reason,
'no-requirements-section'
);
// The other zero shape: the requirements section IS found and scanned, but no
// skill candidates come out of it. Different cause, so a different reason code
// — this one points at extraction, not at header matching.
const parserEmptyJd = `
# Enablement Content Manager
## Requirements
- adult learning principles and instructional design
- blended and scenario-based learning
`;
eq('parser-empty JD extracts zero skills', extractJdSkills(parserEmptyJd).length, 0);
eq(
'zero skills inside a scanned requirements section is reported as no-skill-candidates',
diagnoseExtraction(parserEmptyJd, extractJdSkills(parserEmptyJd)).reason,
'no-skill-candidates'
);
// The reason code must not be read as "the vocabulary is missing these".
// SKILL_TOKEN_RE only captures uppercase-leading tokens, so a lowercase bullet
// extracts nothing even when skill-extract.mjs knows every name in it. Same
// reason code, and the message must stay true here too.
const lowercaseKnownJd = `
# Role
## Requirements
- python and kubernetes experience
`;
eq(
'a lowercase bullet of KNOWN skills still extracts zero candidates',
extractJdSkills(lowercaseKnownJd).length,
0
);
eq(
'the vocabulary does know those names, so the empty result is not a coverage gap',
[...extractSkills('python and kubernetes')].sort().join(','),
'Kubernetes,Python'
);
eq(
'a parser-empty result is reported as no-skill-candidates, not as a vocabulary gap',
diagnoseExtraction(lowercaseKnownJd, extractJdSkills(lowercaseKnownJd)).reason,
'no-skill-candidates'
);
eq(
'the no-skill-candidates message does not claim the vocabulary is missing the terms',
/vocabulary/i.test(diagnoseExtraction(lowercaseKnownJd, []).message),
false
);
// Text copied from a rendered posting page has no list markers. Each
// requirement is a bare line, and the next section is a bare heading
// between blank lines.
const unbulletedJd = `
Qualifications
3+ years experience in a business analyst role
Experience working in Jira or Azure DevOps within an Agile framework
Strong analytical skills
Possess a curiosity around new technology
Python scripting for data pipelines
Core values for Acme employees
Have a strong work ethic
Be a flexible thinker
`;
eq(
'bare requirement lines under a bare heading are extracted',
extractJdSkills(unbulletedJd).sort().join(','),
'Agile,Azure,DevOps,Jira,Python'
);
eq(
'an unbulleted extraction is conclusive',
diagnoseExtraction(unbulletedJd, extractJdSkills(unbulletedJd)),
null
);
// An empty file is its own cause and should not be blamed on header matching.
eq(
'an empty JD is reported as empty-jd',
diagnoseExtraction(' \n \n', []).reason,
'empty-jd'
);
// Regression (#3601): Chinese headers (zh-TW / zh-CN) like 應徵條件 or 職務需求
// must be recognized as requirement section openers, and headers like 工作內容
// or 福利 must close the section.
const zhJd = `
# PHP 後端工程師
## 應徵條件
- 熟悉 PHP、MySQL、Git
- 具 Linux 基本指令能力
## 工作內容
- 開發 RESTful API
- 維護既有 專案
`;
const zhSkills = extractJdSkills(zhJd);
eq('Chinese requirement header (應徵條件) extracts skills', zhSkills.includes('PHP'), true);
eq('Chinese requirement header extracts MySQL', zhSkills.includes('MySQL'), true);
eq('Chinese requirement header extracts Git', zhSkills.includes('Git'), true);
eq('Chinese requirement header extracts Linux', zhSkills.includes('Linux'), true);
eq('Chinese non-requirement header (工作內容) closes requirement section', zhSkills.includes('RESTful'), false);
eq('Chinese header diagnosis is conclusive', diagnoseExtraction(zhJd, zhSkills), null);
// Regression (#5292): a known multi-word skill was split into one-word
// fragments ("Prompt", "Engineering"), none of which canonicalize() knows, so
// a CV listing the skill still got two false gaps.
const phraseJd = '## Requirements\n- Prompt Engineering and Computer Vision experience\n- Experience with Power BI and Tool Calling\n';
const phraseSkills = extractJdSkills(phraseJd);
eq('known multi-word skills are extracted whole, in JD order',
phraseSkills, ['Prompt Engineering', 'Computer Vision', 'Power BI', 'Tool Calling']);
eq('no fragment of a multi-word skill is extracted on its own',
['Prompt', 'Engineering', 'Computer', 'Vision', 'Power', 'BI', 'Tool', 'Calling'].some((t) => phraseSkills.includes(t)),
false);
eq('a CV that lists the multi-word skills has no gap for them',
classifySkillGaps(phraseSkills, '# Skills\nPrompt Engineering, Computer Vision, Power BI, Tool Calling\n').gap,
[]);
eq('a multi-word alias in the JD meets its canonical name in the CV',
classifySkillGaps(extractJdSkills('## Requirements\n- Large Language Models in production\n'), '# Skills\nLLMs\n').existing,
['Large Language Models']);
eq('a lowercase multi-word skill is still not a candidate (same rule as single words)',
extractJdSkills('## Requirements\n- prompt engineering experience\n'),
[]);
eq('"AI" and "Demo" are not reported as skills',
extractJdSkills('## Requirements\n- Experience with a Demo of AI tools in Python\n'),
['Python']);
// Regression (#5292): Chinese requirement text is never a candidate, and a
// block that also names a few Latin tools printed as a complete check.
const zhPartialJd = '任职要求\n- 熟悉 Prompt, Agent, RAG, Memory, Tool Calling 等基础原理\n- 有使用通用大模型、工作流或 AI 编程工具搭建 Demo 的经验\n- 有电商 C 端或直播产品经验者优先\n';
const zhPartialSkills = extractJdSkills(zhPartialJd);
eq('the Chinese repro extracts its Latin skills without fragments or noise',
zhPartialSkills, ['Prompt', 'Agent', 'RAG', 'Memory', 'Tool Calling']);
eq('the Chinese repro is conclusive (skills were classified)',
diagnoseExtraction(zhPartialJd, zhPartialSkills), null);
const zhCoverage = diagnoseCoverage(zhPartialJd);
eq('Chinese requirement text that was not read is reported as partial coverage',
zhCoverage && zhCoverage.reason, 'untokenized-cjk');
eq('partial coverage lists the lines that were not read',
zhCoverage && zhCoverage.unreadLines.length, 3);
eq('a line whose only Chinese is a short connective counts as read',
diagnoseCoverage('任职要求\n- 熟悉 PHP、MySQL、Git\n'), null);
eq('an English JD has no partial-coverage note',
diagnoseCoverage(phraseJd), null);
eq('Chinese text outside a requirements block is not reported',
diagnoseCoverage('## 工作内容\n- 负责直播产品的用户调研与数据分析\n'), null);
// Numbered requirement items: Chinese postings number their requirements
// ("1、", "1．", "（1）", "①") instead of bulleting them, and English ones use
// markdown ordered lists ("1.", "2)"). They are list items, read like "-"
// bullets, not bare lines.
const numberedZhJd = `
任职要求
1、熟悉 Prompt、Agent、RAG 等基础原理
2．掌握 Python，了解 Docker；
（3）熟悉 Kubernetes
①有 Redis 经验
`;
const numberedZhSkills = extractJdSkills(numberedZhJd);
eq(
'numbered zh items (1、 2． （3） ①) are read as requirement items',
[...numberedZhSkills].sort().join(','),
'Agent,Docker,Kubernetes,Prompt,Python,RAG,Redis'
);
eq('numbered zh items make the run conclusive', diagnoseExtraction(numberedZhJd, numberedZhSkills), null);
const numberedEnJd = `
## Requirements
1. Python and Docker
2) Kubernetes
3.5+ years of Terraform
`;
// "3.5+ years" is not an item marker, so that line is not stripped as item 3;
// it is still read, whole, as a bare requirement line next to the items.
eq(
'markdown ordered items are read; a "3.5+ years" line is read as a bare line',
[...extractJdSkills(numberedEnJd)].sort().join(','),
'Docker,Kubernetes,Python,Terraform'
);
// Read as bare lines, numbered items with a blank line between them would
// each look like an isolated heading and close the block after the first.
eq(
'numbered items separated by blank lines are all read',
extractJdSkills('## Requirements\n1. Python\n\n2. Docker\n\n3. Terraform\n').join(','),
'Python,Docker,Terraform'
);
// Regression: plain bullets still extract exactly as before.
eq(
'dash bullets under a zh header still extract',
[...extractJdSkills('任职要求\n- 熟悉 Prompt, Agent, RAG 等基础原理\n')].sort().join(','),
'Agent,Prompt,RAG'
);
// Inline list on the header line, with a full-width colon and CJK separators.
eq(
'inline zh header list with ： and 、 extracts',
[...extractJdSkills('任职要求：Python、Docker、Kubernetes\n')].sort().join(','),
'Docker,Kubernetes,Python'
);
// ...but a full-width-colon sentence with no separator is still not a list.
eq(
'inline zh header with ： and no separator is not read as a list',
extractJdSkills('任职要求：Curious and kind\n').length,
0
);
console.log(`\njd-skill-gap self-test: ${passed} passed, ${failed} failed`);
if (failed > 0) process.exit(1);
}
// ── Main ─────────────────────────────────────────────────────────────
// Derived from the flags this file actually accepts, so `--help` cannot
// describe an option that does not exist.
const USAGE = `Usage:
node jd-skill-gap.mjs <jd-file> [--summary] [--self-test]
--summary human-readable output instead of JSON
--self-test run the built-in checks
--help, -h print this and exit`;
if (isMainModule(import.meta.url)) {
// BEFORE any work. Unhandled, `--help` fell through to the analysis: this
// script printed a full report for it, which is not what the flag asks for
// and hides that it was never recognised.
if (process.argv.slice(2).some((a) => a === '--help' || a === '-h')) {
console.log(USAGE);
process.exit(0);
}
if (selfTestMode) {
runSelfTest();
} else {
if (!jdPathArg || !existsSync(jdPathArg)) {
console.error('Usage: node jd-skill-gap.mjs <jd-file> [--summary]');
console.error(' node jd-skill-gap.mjs --self-test');
process.exit(1);
}
if (!existsSync(CV_PATH)) {
console.error(`Error: cv.md not found at ${CV_PATH}`);
console.error('Create it there, or point CAREER_OPS_ROOT / CAREER_OPS_DATA_DIR (or a .career-ops-data marker) at the directory that already has it.');
process.exit(1);
}
const jdText = readFileSync(jdPathArg, 'utf-8');
const cvText = readFileSync(CV_PATH, 'utf-8');
const jdSkills = extractJdSkills(jdText);
const result = classifySkillGaps(jdSkills, cvText);
// Computed for BOTH output modes. The JSON branch is the one other tools
// consume (modes/pdf.md Step 4 gates on it), so it is the branch that most
// needs to say "nothing was classified" out loud - an empty three-bucket
// object is otherwise indistinguishable from a clean bill of health.
const diagnosis = diagnoseExtraction(jdText, jdSkills);
const coverage = diagnoseCoverage(jdText);
if (summaryMode) {
console.log(`\nJD Skill-Gap Check`);
console.log('─'.repeat(40));
console.log(`JD skills found: ${jdSkills.length}`);
console.log(` ✅ Already in Skills section: ${result.existing.join(', ') || '(none)'}`);
console.log(` 📝 Mentioned in resume prose: ${result.supportedByResume.join(', ') || '(none)'}`);
console.log(` ⚠️ Real gaps (not found anywhere): ${result.gap.join(', ') || '(none)'}`);
// Without a recognized skills heading every match lands in "prose", which
// reads like a CV that lists no skills rather than a heading this script
// did not recognize (#4879).
if (!splitSkillsSection(cvText).namedSkillsText.trim()) {
console.log('');
console.log(' ℹ️ No skills section recognized in cv.md (a heading containing "Skills" or "Competencies", or a top-level');
console.log(' "Tools" / "Technologies" / "Tech Stack" heading), so nothing can be "already in Skills section".');
}
// An empty three-bucket summary is indistinguishable from a clean bill of
// health, and modes/pdf.md Step 4 treats this output as a gate. Say out loud
// that nothing was classified. Still exit 0: this is a warning, not a
// failure, and the user decides how to proceed.
if (diagnosis) {
console.log('');
console.log(' 🚨 LOW CONFIDENCE: this is not a clean result.');
console.log(` ${diagnosis.message}`);
console.log(` (reason: ${diagnosis.reason})`);
}
if (coverage) {
console.log('');
console.log(' ℹ️ PARTIAL COVERAGE: not every requirement was checked.');
console.log(` ${coverage.message}`);
for (const line of coverage.unreadLines) console.log(` - ${line}`);
}
} else {
// Additive key: existing consumers reading the three buckets are unaffected.
// null when the run was conclusive, {reason, message} when it was not.
// partialCoverage: null, or the requirement lines that were not read.
console.log(JSON.stringify({ ...result, lowConfidence: diagnosis, partialCoverage: coverage }, null, 2));
}
}
} // end CLI guard