@phuthuycoding/markcv 0.1.0

package/dist/core/lint.js

@@ -0,0 +1,188 @@
+import { BOAST, WEAK_VERBS, SCALE_HINTS, PRESENT_VERBS, TECH_TOKENS, HEAVY_TOKENS, IC_TITLES, PEOPLE_MGMT } from "./rules.js";
+const BULLET_RE = /^\s*[*-]\s+(.*)$/;
+const H2_RE = /^##\s+(.*)$/;
+const H3_RE = /^###\s+(.*)$/;
+const META_RE = /^\*\*(.+?)\*\*\s*\|\s*(.*)$/;
+/** A finished date range: no Present/Now marker. */
+// 'hiện tại' is Vietnamese for 'present' - kept so Vietnamese-language CVs work too.
+const ENDED_RE = /\d{4}\s*[-–—]\s*(?!.*(present|now|current|hiện tại))/i;
+const strip = (s) => s.replace(/\*\*/g, "").replace(/`/g, "").trim();
+const lower = (s) => strip(s).toLowerCase();
+export function lint(raw) {
+    const lines = raw.split("\n");
+    const findings = [];
+    const ctx = { section: "", jobTitle: "", jobEnded: false };
+    const bullets = [];
+    const skillTokens = new Map();
+    const evidence = new Set();
+    // Evidence can appear on ANY line outside SKILLS — including the prose in
+    // PROJECT HIGHLIGHTS, not just bullets.
+    {
+        let sec = "";
+        for (const line of lines) {
+            const h = line.match(H2_RE);
+            if (h) {
+                sec = strip(h[1]).toUpperCase();
+                continue;
+            }
+            if (sec.includes("SKILL"))
+                continue;
+            const flat = lower(line);
+            for (const t of TECH_TOKENS)
+                if (flat.includes(t))
+                    evidence.add(t);
+        }
+    }
+    lines.forEach((line, idx) => {
+        const no = idx + 1;
+        const h2 = line.match(H2_RE);
+        if (h2) {
+            ctx.section = strip(h2[1]).toUpperCase();
+            ctx.jobTitle = "";
+            ctx.jobEnded = false;
+            if (/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/u.test(line)) {
+                findings.push({
+                    rule: "ats-emoji", severity: "warn", line: no, excerpt: strip(h2[1]),
+                    message: "Emoji in a heading can break fonts or confuse ATS parsers.",
+                    suggestion: "Remove the emoji from the heading.",
+                });
+            }
+            return;
+        }
+        const h3 = line.match(H3_RE);
+        if (h3) {
+            ctx.jobTitle = strip(h3[1]);
+            return;
+        }
+        const meta = line.match(META_RE);
+        if (meta) {
+            ctx.jobTitle = strip(meta[1]);
+            ctx.jobEnded = ENDED_RE.test(line);
+            return;
+        }
+        const bullet = line.match(BULLET_RE);
+        if (!bullet)
+            return;
+        const text = bullet[1];
+        const flat = lower(text);
+        bullets.push({ line: no, text: strip(text), section: ctx.section });
+        if (ctx.section.includes("SKILL")) {
+            for (const t of TECH_TOKENS)
+                if (flat.includes(t))
+                    skillTokens.set(t, no);
+        }
+        // 1. overselling
+        for (const w of BOAST) {
+            if (flat.includes(w)) {
+                findings.push({
+                    rule: "over-claim", severity: "warn", line: no, excerpt: w,
+                    message: `"${w}" is unverifiable self-praise — readers skip straight past it.`,
+                    suggestion: "Replace it with a fact: a number, a scale, or a before/after result.",
+                });
+            }
+        }
+        // 2. underselling: a weak verb next to real scale
+        const weak = WEAK_VERBS.find((w) => flat.startsWith(w) || flat.includes(` ${w} `));
+        if (weak && SCALE_HINTS.some((h) => flat.includes(h)) && /\d/.test(flat)) {
+            findings.push({
+                rule: "under-claim", severity: "error", line: no, excerpt: weak,
+                message: `"${weak}" understates the scale described on the same line.`,
+                suggestion: "If you actually did or led it, say Led / Built / Designed.",
+            });
+        }
+        // 3. tense: a finished job written in the present
+        if (ctx.jobEnded) {
+            const first = flat.replace(/^\*\*[^*]+:\*\*\s*/, "").split(/\s+/)[0]?.replace(/[^a-z]/g, "");
+            const firstAfterLabel = strip(text).replace(/^[^:]+:\s*/, "").split(/\s+/)[0]?.toLowerCase();
+            const verb = PRESENT_VERBS.find((v) => v === first || v === firstAfterLabel);
+            if (verb) {
+                findings.push({
+                    rule: "tense", severity: "error", line: no, excerpt: verb,
+                    message: `"${ctx.jobTitle}" has ended, but this bullet is in the present tense ("${verb}").`,
+                    suggestion: "Switch it to past tense.",
+                });
+            }
+        }
+        // 4. experience bullet with no number at all
+        if ((ctx.section.includes("EXPERIENCE") || ctx.section.includes("PROJECT")) && !/\d/.test(flat) && flat.length > 60) {
+            findings.push({
+                rule: "no-metric", severity: "info", line: no, excerpt: strip(text).slice(0, 60),
+                message: "A long bullet with no number in it.",
+                suggestion: "Add a scale or a before/after result if you have one.",
+            });
+        }
+        // 5. bullet too long
+        if (strip(text).length > 320) {
+            findings.push({
+                rule: "long-bullet", severity: "info", line: no, excerpt: `${strip(text).length} chars`,
+                message: "Long enough that a skimming reader will skip it.",
+                suggestion: "Split it in two, or move the detail into a project section.",
+            });
+        }
+        // 6. role mismatch: IC title, people-management wording
+        const titleLower = ctx.jobTitle.toLowerCase();
+        if (IC_TITLES.some((t) => titleLower.includes(t)) && !/(lead|manager|head|director)/.test(titleLower)) {
+            const mgmt = PEOPLE_MGMT.find((m) => flat.includes(m));
+            if (mgmt && /\d/.test(flat)) {
+                findings.push({
+                    rule: "role-mismatch", severity: "warn", line: no, excerpt: mgmt,
+                    message: `"${ctx.jobTitle}" is an IC title, but this bullet reads like people management.`,
+                    suggestion: "Make the technical/advisory nature explicit, or drop the headcount.",
+                });
+            }
+        }
+    });
+    // 7. skill listed under SKILLS with no supporting experience
+    for (const [token, line] of skillTokens) {
+        if (!evidence.has(token)) {
+            const heavy = HEAVY_TOKENS.includes(token);
+            findings.push({
+                rule: "unsupported-skill",
+                severity: heavy ? "warn" : "info",
+                line, excerpt: token,
+                message: heavy
+                    ? `"${token}" appears only under SKILLS — this is one interviewers dig into.`
+                    : `"${token}" appears only under SKILLS (harmless for a commodity technology).`,
+                suggestion: heavy
+                    ? "Add an experience line that backs it up, or drop it from SKILLS."
+                    : "Safe to ignore unless the JD leans on it.",
+            });
+        }
+    }
+    // 8. two bullets saying the same thing.
+    // SKILLS is excluded: a stack list naturally shares words with experience bullets,
+    // which is not repetition.
+    const comparable = bullets.filter((b) => !b.section.includes("SKILL"));
+    for (let i = 0; i < comparable.length; i++) {
+        for (let j = i + 1; j < comparable.length; j++) {
+            const sim = similarity(comparable[i].text, comparable[j].text);
+            if (sim >= 0.6) {
+                findings.push({
+                    rule: "duplicate", severity: "warn", line: comparable[j].line,
+                    excerpt: comparable[j].text.slice(0, 60),
+                    message: `Says the same thing as line ${comparable[i].line} (${Math.round(sim * 100)}%).`,
+                    suggestion: "Merge them, or drop one.",
+                });
+            }
+        }
+    }
+    // 9. missing basic contact details
+    const head = raw.slice(0, 1200).toLowerCase();
+    if (!/@/.test(head)) {
+        findings.push({ rule: "contact", severity: "error", line: 1, excerpt: "email",
+            message: "No email address found in the CV header.", suggestion: "Add an **Email:** line." });
+    }
+    return findings.sort((a, b) => a.line - b.line);
+}
+/** Similarity over meaningful words, ignoring short filler words. */
+function similarity(a, b) {
+    const words = (s) => new Set(s.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length > 3));
+    const A = words(a), B = words(b);
+    if (A.size < 4 || B.size < 4)
+        return 0;
+    let shared = 0;
+    for (const w of A)
+        if (B.has(w))
+            shared++;
+    return shared / Math.min(A.size, B.size);
+}

package/dist/core/markdown.d.ts

@@ -0,0 +1,10 @@
+import type { CvDoc } from "../types.js";
+export declare function parseCv(raw: string): CvDoc;
+/**
+ * Markdown -> page body HTML.
+ * The header (name + contact lines) is wrapped in .header so the portrait can be
+ * positioned against it, and contact lines are grouped into .contacts so they can
+ * be laid out as one block.
+ */
+export declare function renderBody(raw: string, photoHtml: string): string;
+export declare function buildHtml(body: string, css: string, title?: string): string;

package/dist/core/markdown.js

@@ -0,0 +1,76 @@
+import MarkdownIt from "markdown-it";
+const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
+/** A header contact line: `**Label:** value` (no `|`, unlike a job-title line). */
+const CONTACT_RE = /^<p><strong>[^<]+:<\/strong>[^|]*<\/p>$/;
+/** A job-title line: `**Job Title** | 2020 - 2021`. */
+const META_RE = /^<p><strong>.*\|.*<\/p>$/;
+export function parseCv(raw) {
+    const lines = raw.split("\n");
+    const sections = [];
+    lines.forEach((line, i) => {
+        if (line.startsWith("## ")) {
+            if (sections.length)
+                sections[sections.length - 1].end = i - 1;
+            sections.push({ title: line.slice(3).trim(), start: i, end: lines.length - 1 });
+        }
+    });
+    return { raw, lines, sections };
+}
+/**
+ * Markdown -> page body HTML.
+ * The header (name + contact lines) is wrapped in .header so the portrait can be
+ * positioned against it, and contact lines are grouped into .contacts so they can
+ * be laid out as one block.
+ */
+export function renderBody(raw, photoHtml) {
+    const html = md.render(raw);
+    const blocks = html.split("\n").filter((l) => l.trim() !== "");
+    const out = [];
+    let headerOpen = false;
+    let contactsOpen = false;
+    const closeContacts = () => {
+        if (contactsOpen) {
+            out.push("</div>");
+            contactsOpen = false;
+        }
+    };
+    for (const block of blocks) {
+        const isContact = headerOpen && CONTACT_RE.test(block);
+        if (!isContact)
+            closeContacts();
+        if (block.startsWith("<h1>")) {
+            out.push('<div class="header">', photoHtml, block);
+            headerOpen = true;
+            continue;
+        }
+        if (block.startsWith("<h2>") && headerOpen) {
+            out.push("</div>"); // close .header before the first section
+            headerOpen = false;
+        }
+        if (isContact) {
+            if (!contactsOpen) {
+                out.push('<div class="contacts">');
+                contactsOpen = true;
+            }
+            out.push(block.replace("<p>", '<p class="contact">'));
+            continue;
+        }
+        if (META_RE.test(block)) {
+            out.push(block.replace("<p>", '<p class="meta">'));
+            continue;
+        }
+        out.push(block);
+    }
+    closeContacts();
+    if (headerOpen)
+        out.push("</div>");
+    return out.join("\n");
+}
+export function buildHtml(body, css, title = "CV") {
+    return [
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">',
+        `<title>${title}</title><style>${css}</style></head><body>`,
+        body,
+        "</body></html>",
+    ].join("");
+}

package/dist/core/photo.d.ts

@@ -0,0 +1,12 @@
+export interface PhotoResult {
+    html: string;
+    file: string | null;
+    bytes: number;
+    warning?: string;
+}
+/**
+ * Return the portrait as a base64-embedded tag, or an empty placeholder box.
+ * Embedding keeps the HTML self-contained — it survives being moved or emailed,
+ * and Chrome's PDF export never depends on a relative path.
+ */
+export declare function photoBlock(mdPath: string, explicit?: string | null): PhotoResult;

package/dist/core/photo.js

@@ -0,0 +1,42 @@
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+const CANDIDATES = ["photo.jpg", "photo.jpeg", "photo.png", "photo.webp", "avatar.jpg", "avatar.png"];
+const MIME = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp",
+};
+/** Above this size the photo pushes the PDF past what job portals accept. */
+const WARN_BYTES = 400 * 1024;
+/**
+ * Return the portrait as a base64-embedded tag, or an empty placeholder box.
+ * Embedding keeps the HTML self-contained — it survives being moved or emailed,
+ * and Chrome's PDF export never depends on a relative path.
+ */
+export function photoBlock(mdPath, explicit) {
+    if (explicit === null)
+        return { html: "", file: null, bytes: 0 }; // explicitly disabled
+    const folder = dirname(resolve(mdPath));
+    const found = explicit
+        ? (existsSync(explicit) ? explicit : null)
+        : CANDIDATES.map((n) => resolve(folder, n)).find(existsSync) ?? null;
+    if (!found) {
+        return {
+            html: '<div class="photo-empty">PHOTO</div>',
+            file: null,
+            bytes: 0,
+        };
+    }
+    const bytes = statSync(found).size;
+    const mime = MIME[extname(found).toLowerCase()] ?? "image/jpeg";
+    const b64 = readFileSync(found).toString("base64");
+    const result = {
+        html: `<img class="photo" src="data:${mime};base64,${b64}" alt="">`,
+        file: found,
+        bytes,
+    };
+    if (bytes > WARN_BYTES) {
+        result.warning =
+            `Photo is ${(bytes / 1024 / 1024).toFixed(1)}MB and will bloat the PDF. ` +
+                `Compress it first: sips -Z 800 -s format jpeg -s formatOptions 88 <photo> --out photo.jpg`;
+    }
+    return result;
+}

package/dist/core/render.d.ts

@@ -0,0 +1,28 @@
+import type { RenderOptions } from "../types.js";
+export interface PageBox {
+    widthPx: number;
+    heightPx: number;
+}
+/** Read the theme's `@page { margin: ... }` to derive the real printable area. */
+export declare function pageBoxFromCss(css: string): PageBox;
+export declare function loadTheme(name?: string): string;
+/** Measurements taken in the browser at the printable width. */
+export interface RawMeasure {
+    contentHeight: number;
+    blocks: {
+        tag: string;
+        title: string;
+        top: number;
+        clusterHeight: number;
+    }[];
+}
+export interface RenderResult {
+    htmlPath: string;
+    pdfPath?: string;
+    pageBox: PageBox;
+    measure: RawMeasure;
+    pdfPages?: number;
+    photoFile: string | null;
+    photoWarning?: string;
+}
+export declare function render(opts: RenderOptions): Promise<RenderResult>;

package/dist/core/render.js

@@ -0,0 +1,104 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import puppeteer from "puppeteer-core";
+import { renderBody, buildHtml } from "./markdown.js";
+import { photoBlock } from "./photo.js";
+import { findChrome } from "./browser.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MM_TO_PX = 96 / 25.4;
+const A4 = { widthMm: 210, heightMm: 297 };
+/** Read the theme's `@page { margin: ... }` to derive the real printable area. */
+export function pageBoxFromCss(css) {
+    const at = css.match(/@page\s*{([^}]*)}/)?.[1] ?? "";
+    const margin = at.match(/margin:\s*([^;]+);/)?.[1]?.trim() ?? "10mm";
+    const parts = margin.split(/\s+/).map((v) => parseFloat(v) || 0);
+    const [top, right, bottom, left] = parts.length === 1 ? [parts[0], parts[0], parts[0], parts[0]]
+        : parts.length === 2 ? [parts[0], parts[1], parts[0], parts[1]]
+            : parts.length === 3 ? [parts[0], parts[1], parts[2], parts[1]]
+                : [parts[0], parts[1], parts[2], parts[3]];
+    return {
+        widthPx: Math.round((A4.widthMm - left - right) * MM_TO_PX),
+        heightPx: Math.round((A4.heightMm - top - bottom) * MM_TO_PX),
+    };
+}
+export function loadTheme(name = "classic") {
+    const candidates = [
+        resolve(HERE, "../../themes", `${name}.css`),
+        resolve(HERE, "../../../themes", `${name}.css`),
+        resolve(process.cwd(), "themes", `${name}.css`),
+        resolve(name),
+    ];
+    const found = candidates.find(existsSync);
+    if (!found)
+        throw new Error(`Theme "${name}" not found. Available: classic, compact.`);
+    return readFileSync(found, "utf8");
+}
+function countPdfPages(path) {
+    const buf = readFileSync(path);
+    const matches = buf.toString("latin1").match(/\/Type\s*\/Page[^s]/g);
+    return matches ? matches.length : 0;
+}
+export async function render(opts) {
+    const mdPath = resolve(opts.input);
+    const raw = readFileSync(mdPath, "utf8");
+    const css = loadTheme(opts.theme);
+    const pageBox = pageBoxFromCss(css);
+    const photo = photoBlock(mdPath, opts.photo);
+    const html = buildHtml(renderBody(raw, photo.html), css);
+    const htmlPath = opts.html
+        ? resolve(opts.html)
+        : join(tmpdir(), `markcv-${Date.now()}.html`);
+    mkdirSync(dirname(htmlPath), { recursive: true });
+    writeFileSync(htmlPath, html, "utf8");
+    let browser;
+    try {
+        browser = await puppeteer.launch({
+            executablePath: findChrome(),
+            headless: true,
+            args: ["--no-sandbox", "--disable-gpu", "--font-render-hinting=none"],
+        });
+        const page = await browser.newPage();
+        // Measure at the printable width, otherwise text wraps differently than it prints.
+        await page.setViewport({ width: pageBox.widthPx, height: pageBox.heightPx });
+        await page.goto(`file://${htmlPath}`, { waitUntil: "networkidle0" });
+        const measure = await page.evaluate(() => {
+            const blocks = [...document.querySelectorAll("h1, h2, h3")].map((el) => {
+                const top = el.getBoundingClientRect().top + window.scrollY;
+                // h2/h3 use break-after: avoid, so they stay glued to the element after them.
+                const next = el.nextElementSibling;
+                const bottom = next
+                    ? next.getBoundingClientRect().bottom + window.scrollY
+                    : el.getBoundingClientRect().bottom + window.scrollY;
+                return {
+                    tag: el.tagName,
+                    title: (el.textContent ?? "").trim().slice(0, 48),
+                    top: Math.round(top),
+                    clusterHeight: Math.round(bottom - top),
+                };
+            });
+            return { contentHeight: Math.round(document.body.scrollHeight), blocks };
+        });
+        let pdfPages;
+        let pdfPath;
+        if (opts.pdf) {
+            pdfPath = resolve(opts.pdf);
+            mkdirSync(dirname(pdfPath), { recursive: true });
+            await page.pdf({
+                path: pdfPath,
+                printBackground: true,
+                preferCSSPageSize: true,
+                displayHeaderFooter: false,
+            });
+            pdfPages = countPdfPages(pdfPath);
+        }
+        return {
+            htmlPath, pdfPath, pageBox, measure, pdfPages,
+            photoFile: photo.file, photoWarning: photo.warning,
+        };
+    }
+    finally {
+        await browser?.close();
+    }
+}

package/dist/core/rules.d.ts

@@ -0,0 +1,20 @@
+/** Word lists for lint. Kept separate so they can be tuned without touching logic. */
+/** Self-praise adjectives — readers skip them, interviewers distrust them. */
+export declare const BOAST: string[];
+/** Understating verbs — dangerous next to work of real scale. */
+export declare const WEAK_VERBS: string[];
+/** Markers of scale — suspicious when paired with a weak verb. */
+export declare const SCALE_HINTS: string[];
+/** Base-form verbs that often start a bullet — used to catch present-tense slips. */
+export declare const PRESENT_VERBS: string[];
+/** Tech keywords commonly listed under SKILLS with nothing backing them. */
+export declare const TECH_TOKENS: string[];
+/** Individual-contributor titles — people-management wording next to them signals a mismatch. */
+export declare const IC_TITLES: string[];
+export declare const PEOPLE_MGMT: string[];
+/**
+ * Keywords an interviewer will dig into. Claiming these without evidence falls apart
+ * under questioning. The rest (MySQL, Redis, Docker…) are perfectly normal to list
+ * under SKILLS and not worth warning about.
+ */
+export declare const HEAVY_TOKENS: string[];

package/dist/core/rules.js

@@ -0,0 +1,53 @@
+/** Word lists for lint. Kept separate so they can be tuned without touching logic. */
+/** Self-praise adjectives — readers skip them, interviewers distrust them. */
+export const BOAST = [
+    "spearheaded", "championed", "rigorous", "rigorously", "comprehensive", "world-class",
+    "cutting-edge", "state-of-the-art", "best-in-class", "excellence", "seamlessly",
+    "significantly", "dramatically", "highly skilled", "expertly", "passionate",
+    "guru", "ninja", "rockstar", "visionary", "unparalleled", "exceptional",
+    "extensive experience", "proven track record", "results-driven", "synergy",
+];
+/** Understating verbs — dangerous next to work of real scale. */
+export const WEAK_VERBS = [
+    "assisted", "helped", "participated in", "involved in", "took part in",
+    "advised on", "supported", "contributed to", "worked on", "was responsible for",
+    "responsible for", "familiar with", "exposure to",
+];
+/** Markers of scale — suspicious when paired with a weak verb. */
+export const SCALE_HINTS = [
+    "services", "engineers", "developers", "squads", "users", "staff", "events",
+    "microservices", "million", "requests", "customers", "merchants", "teams",
+];
+/** Base-form verbs that often start a bullet — used to catch present-tense slips. */
+export const PRESENT_VERBS = [
+    "mentor", "advise", "lead", "build", "manage", "review", "run", "own", "drive",
+    "design", "maintain", "support", "coordinate", "deliver", "define", "set",
+    "introduce", "improve", "handle", "track", "report", "work",
+];
+/** Tech keywords commonly listed under SKILLS with nothing backing them. */
+export const TECH_TOKENS = [
+    "kubernetes", "docker", "kafka", "rabbitmq", "spark", "redis", "postgresql", "mysql",
+    "mongodb", "graphql", "react", "next.js", "vue", "angular", "svelte", "typescript",
+    "golang", "python", "java", "spring boot", "nestjs", "node.js", "php", "laravel",
+    "symfony", "flutter", "react native", "terraform", "aws", "gcp", "azure",
+    "opentelemetry", "grafana", "prometheus", "elk", "elasticsearch", "playwright",
+    "cypress", "jest", "vitest", "oauth", "oidc", "jwt", "ddd", "clean architecture",
+    "event-driven", "microservices", "helm", "ci/cd",
+];
+/** Individual-contributor titles — people-management wording next to them signals a mismatch. */
+export const IC_TITLES = ["engineer", "developer", "programmer", "architect", "specialist"];
+export const PEOPLE_MGMT = [
+    "managed a team of", "team of", "direct reports", "headcount", "performance review",
+    "hiring", "interviewing",
+];
+/**
+ * Keywords an interviewer will dig into. Claiming these without evidence falls apart
+ * under questioning. The rest (MySQL, Redis, Docker…) are perfectly normal to list
+ * under SKILLS and not worth warning about.
+ */
+export const HEAVY_TOKENS = [
+    "kubernetes", "kafka", "spark", "terraform", "opentelemetry", "playwright",
+    "cypress", "event-driven", "microservices", "ddd", "clean architecture",
+    "oauth", "oidc", "graphql", "spring boot", "flutter", "react native", "helm",
+    "aws", "gcp", "azure", "elasticsearch", "prometheus",
+];

package/dist/core/tailor.d.ts

@@ -0,0 +1,10 @@
+import type { TailorReport } from "../types.js";
+/**
+ * Compare a CV against a job description.
+ *
+ * The goal is not keyword stuffing. It surfaces three things: what the JD asks for
+ * with no evidence in the CV, which keywords live only under SKILLS (those fall apart
+ * in a deep interview), and which bullets are unrelated to the JD — so you cut those
+ * before cutting anything valuable.
+ */
+export declare function tailor(cvRaw: string, jdRaw: string): TailorReport;

package/dist/core/tailor.js

@@ -0,0 +1,82 @@
+import { TECH_TOKENS } from "./rules.js";
+const BULLET_RE = /^\s*[*-]\s+(.*)$/;
+const H2_RE = /^##\s+(.*)$/;
+/** Multi-word phrases that must match as a whole. */
+const PHRASES = [
+    "clean architecture", "event-driven", "domain-driven", "spring boot", "next.js",
+    "react native", "ci/cd", "unit test", "integration test", "e2e", "end-to-end",
+    "code review", "system design", "distributed systems", "message queue",
+    "observability", "monitoring", "incident", "agile", "scrum", "mentoring",
+];
+const norm = (s) => s.toLowerCase().replace(/\*\*/g, "").replace(/`/g, "");
+/**
+ * Compare a CV against a job description.
+ *
+ * The goal is not keyword stuffing. It surfaces three things: what the JD asks for
+ * with no evidence in the CV, which keywords live only under SKILLS (those fall apart
+ * in a deep interview), and which bullets are unrelated to the JD — so you cut those
+ * before cutting anything valuable.
+ */
+export function tailor(cvRaw, jdRaw) {
+    const cv = norm(cvRaw);
+    const jd = norm(jdRaw);
+    const lines = cvRaw.split("\n");
+    const wanted = new Set();
+    for (const t of [...TECH_TOKENS, ...PHRASES])
+        if (jd.includes(t))
+            wanted.add(t);
+    // Where each keyword shows up: under SKILLS, or in real experience.
+    const inSkills = new Map();
+    const inEvidence = new Map();
+    let section = "";
+    lines.forEach((line, idx) => {
+        const h2 = line.match(H2_RE);
+        if (h2) {
+            section = h2[1].toUpperCase();
+            return;
+        }
+        const flat = norm(line);
+        const target = section.includes("SKILL") ? inSkills : inEvidence;
+        for (const t of wanted)
+            if (flat.includes(t) && !target.has(t))
+                target.set(t, idx + 1);
+    });
+    const missing = [...wanted]
+        .filter((t) => !inSkills.has(t) && !inEvidence.has(t))
+        .map((keyword) => ({
+        keyword,
+        hint: `The JD mentions "${keyword}" but the CV does not. Add a bullet if you genuinely have it; otherwise leave it out rather than stuffing it in.`,
+    }));
+    const unsupported = [...wanted]
+        .filter((t) => inSkills.has(t) && !inEvidence.has(t))
+        .map((keyword) => ({
+        keyword,
+        hint: `"${keyword}" appears only under SKILLS. Interviewers will dig into it — it needs an experience line behind it.`,
+    }));
+    const covered = [...wanted]
+        .filter((t) => inEvidence.has(t))
+        .map((keyword) => ({ keyword, evidenceLine: inEvidence.get(keyword) }));
+    // Experience bullets that touch none of the JD keywords.
+    const irrelevant = [];
+    section = "";
+    lines.forEach((line, idx) => {
+        const h2 = line.match(H2_RE);
+        if (h2) {
+            section = h2[1].toUpperCase();
+            return;
+        }
+        if (!section.includes("EXPERIENCE"))
+            return;
+        const m = line.match(BULLET_RE);
+        if (!m)
+            return;
+        const flat = norm(m[1]);
+        if (flat.length < 40)
+            return;
+        const touches = [...wanted].some((t) => flat.includes(t));
+        if (!touches)
+            irrelevant.push({ line: idx + 1, excerpt: m[1].replace(/\*\*/g, "").slice(0, 70) });
+    });
+    const score = wanted.size === 0 ? 0 : Math.round((covered.length / wanted.size) * 100);
+    return { missing, unsupported, irrelevant, covered, score };
+}

package/dist/core/variants.d.ts

@@ -0,0 +1,16 @@
+/** Start a tailored copy from a master file. It only copies; trimming is up to you or the agent. */
+export declare function newVariant(master: string, name: string): string;
+export interface VariantInfo {
+    file: string;
+    name: string;
+    lines: number;
+    bullets: number;
+    sections: string[];
+}
+export declare function listVariants(dir: string): VariantInfo[];
+/** Compare two versions: which bullets exist on only one side. */
+export declare function diffVariants(a: string, b: string): {
+    onlyInA: string[];
+    onlyInB: string[];
+    shared: number;
+};