resuml 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -409,56 +409,86 @@ declare namespace themeRender {
   export { themeRender_injectCss as injectCss, themeRender_renderTheme as renderTheme };
 }
 
-type AtsCheckCategory = 'contact' | 'content' | 'structure' | 'keywords';
+type Tier = 'parsing' | 'match' | 'recruiter';
 type AtsCheckWeight = 'high' | 'medium' | 'low';
 type AtsRating = 'excellent' | 'good' | 'needs-work' | 'poor';
-type AtsFitLevel = 'strong' | 'partial' | 'weak';
-interface AtsCheck {
+type CheckStatus = 'pass' | 'warn' | 'fail' | 'skipped';
+type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+interface CheckResult {
     id: string;
-    category: AtsCheckCategory;
-    weight: AtsCheckWeight;
-    passed: boolean;
+    tier: Tier;
+    status: CheckStatus;
     score: number;
+    weight: AtsCheckWeight;
     message: string;
-    suggestion?: string;
+    hints: string[];
 }
-interface AtsKeywordMatch {
-    matched: string[];
-    missing: string[];
-    extra: string[];
-    matchPercentage: number;
+interface TierResult {
+    score: number;
+    grade: Grade;
+    checks: CheckResult[];
 }
-interface AtsFitAssessment {
-    level: AtsFitLevel;
-    message: string;
+interface KnockoutSignal {
+    signal: string;
+    evidence: string;
+    recommendation: string;
 }
-interface AtsResult {
+interface TieredAtsResult {
     score: number;
     rating: AtsRating;
-    checks: AtsCheck[];
-    keywords?: AtsKeywordMatch;
-    fitAssessment?: AtsFitAssessment;
+    tiers: {
+        parsing: TierResult;
+        match?: TierResult;
+        recruiter: TierResult;
+    };
+    knockouts: KnockoutSignal[];
     summary: string;
 }
 interface AtsOptions {
     language?: string;
     jobDescription?: string;
     threshold?: number;
+    config?: AtsConfig;
+}
+interface AtsConfig {
+    weights: {
+        tiers: {
+            parsing: number;
+            match: number;
+            recruiter: number;
+        };
+        checks: Record<string, AtsCheckWeight>;
+    };
+    thresholds: {
+        rating: {
+            excellent: number;
+            good: number;
+            needsWork: number;
+        };
+        grade: {
+            A: number;
+            B: number;
+            C: number;
+            D: number;
+        };
+        seniorYoeCutoff: number;
+        wordCount: {
+            min: number;
+            max: number;
+            seniorMax: number;
+        };
+        bulletsPerRole: {
+            min: number;
+            max: number;
+            seniorMax: number;
+        };
+    };
+    disable: string[];
+    locale: string;
 }
 
-/**
- * Run ATS analysis on a resume.
- *
- * Performs deterministic, offline checks:
- * 1. Generic best-practice checks (contact, content, structure)
- * 2. Optional job-description keyword matching
- *
- * @param resume - Validated resume data
- * @param options - ATS analysis options
- * @returns Full ATS analysis result with score, checks, and suggestions
- */
-declare function analyzeAts(resume: ResumeSchema, options?: AtsOptions): AtsResult;
+declare function analyzeAts(resume: ResumeSchema, options?: AtsOptions): TieredAtsResult;
 
 declare const program: Command;
 
-export { type AtsOptions, type AtsResult, analyzeAts, loadResumeFiles, loadTheme, processResumeData, program, themeRender };
+export { type AtsOptions, type TieredAtsResult, analyzeAts, loadResumeFiles, loadTheme, processResumeData, program, themeRender };

package/dist/index.js

@@ -5,10 +5,13 @@ import {
   analyzeAts,
   generateResumeYaml,
   getInstalledVersion,
+  getRubricEntry,
   isThemeInstalled,
+  listRubricMarkdown,
+  loadConfig,
   loadTheme,
   processResumeData
-} from "./chunk-GRIYYG45.js";
+} from "./chunk-R4MD5YMV.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -129,97 +132,85 @@ function handleCommandError(error, command, debug = false) {
 }
 
 // src/commands/validate.ts
-function formatAtsReport(result, debug, chalk6) {
-  const scoreColor = result.score >= 75 ? chalk6.green : result.score >= 60 ? chalk6.yellow : chalk6.red;
+function formatAtsReport(result, debug, chalk7) {
+  const scoreColor = result.score >= 75 ? chalk7.green : result.score >= 60 ? chalk7.yellow : chalk7.red;
   console.log("");
-  console.log(chalk6.bold("\u2550\u2550\u2550 ATS Analysis Report \u2550\u2550\u2550"));
+  console.log(chalk7.bold("=== ATS Analysis Report ==="));
   console.log("");
-  console.log(`  Score: ${scoreColor(chalk6.bold(`${result.score}/100`))} (${result.rating.replace("-", " ")})`);
+  console.log(
+    `  Score: ${scoreColor(chalk7.bold(`${result.score}/100`))} (${result.rating.replace("-", " ")})`
+  );
   console.log(`  ${result.summary}`);
   console.log("");
-  const categories = {};
-  for (const check of result.checks) {
-    const list = categories[check.category];
-    if (!list) {
-      categories[check.category] = [check];
-    } else {
-      list.push(check);
-    }
-  }
-  const categoryLabels = {
-    contact: "Contact Information",
-    content: "Content Quality",
-    structure: "Resume Structure",
-    keywords: "Keywords"
+  const tierLabels = {
+    parsing: "Parsing",
+    recruiter: "Recruiter",
+    match: "JD Match"
   };
-  for (const [cat, checks] of Object.entries(categories)) {
-    const label = categoryLabels[cat] || cat;
-    console.log(chalk6.bold(`  ${label}`));
-    for (const check of checks) {
-      if (!debug && check.passed) continue;
-      const icon = check.passed ? chalk6.green("\u2713") : chalk6.red("\u2717");
-      const scoreText = chalk6.dim(`[${check.score}]`);
+  for (const [tierName, tier] of Object.entries(result.tiers)) {
+    const label = tierLabels[tierName] ?? tierName;
+    console.log(chalk7.bold(`  ${label} (${tier.score}/100, grade ${tier.grade})`));
+    for (const check of tier.checks) {
+      if (!debug && (check.status === "pass" || check.status === "skipped")) continue;
+      const icon = check.status === "pass" ? chalk7.green("v") : check.status === "skipped" ? chalk7.dim("-") : check.status === "warn" ? chalk7.yellow("!") : chalk7.red("x");
+      const scoreText = chalk7.dim(`[${check.score}]`);
       console.log(`    ${icon} ${check.message} ${scoreText}`);
-      if (!check.passed && check.suggestion) {
-        console.log(chalk6.dim(`      \u2192 ${check.suggestion}`));
+      for (const hint of check.hints) {
+        console.log(chalk7.dim(`      -> ${hint}`));
       }
     }
     console.log("");
   }
-  if (result.keywords) {
-    console.log(chalk6.bold("  Job Description Match"));
-    const kw = result.keywords;
-    const matchColor = kw.matchPercentage >= 70 ? chalk6.green : kw.matchPercentage >= 50 ? chalk6.yellow : chalk6.red;
-    console.log(`    Match: ${matchColor(`${kw.matchPercentage}%`)} (${kw.matched.length}/${kw.matched.length + kw.missing.length} keywords)`);
-    if (kw.matched.length > 0) {
-      console.log(chalk6.green(`    \u2713 Matched: ${kw.matched.join(", ")}`));
-    }
-    if (kw.missing.length > 0) {
-      console.log(chalk6.red(`    \u2717 Missing: ${kw.missing.join(", ")}`));
-      console.log(chalk6.dim("      \u2192 Consider incorporating these keywords into your resume where relevant."));
+  if (result.knockouts.length > 0) {
+    console.log(chalk7.bold("  Knockout Signals"));
+    for (const k of result.knockouts) {
+      console.log(chalk7.red(`    ! ${k.signal}: ${k.evidence}`));
+      console.log(chalk7.dim(`      -> ${k.recommendation}`));
     }
     console.log("");
   }
-  console.log(chalk6.dim("\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550"));
+  console.log(chalk7.dim("==========================="));
 }
 async function validateAction(options) {
-  const chalk6 = (await import("chalk")).default;
-  console.log(chalk6.blue("Starting resuml validate..."));
+  const chalk7 = (await import("chalk")).default;
+  console.log(chalk7.blue("Starting resuml validate..."));
   try {
     const inputPath = options.resume;
     const { yamlContents } = await loadResumeFiles(inputPath);
-    console.log(chalk6.blue("Validating resume data..."));
+    console.log(chalk7.blue("Validating resume data..."));
     let resumeData;
     try {
       resumeData = await processResumeData(yamlContents);
-      console.log(chalk6.green("\u2713 Resume data is valid against the schema!"));
+      console.log(chalk7.green("\u2713 Resume data is valid against the schema!"));
     } catch (error) {
       handleCommandError(error, "validate", options.debug);
       return;
     }
     if (options.ats) {
-      console.log(chalk6.blue("Running ATS analysis..."));
+      console.log(chalk7.blue("Running ATS analysis..."));
       let jobDescription;
       if (options.jd) {
         try {
           jobDescription = fs3.readFileSync(options.jd, "utf8");
         } catch {
-          console.error(chalk6.red(`Failed to read job description file: ${options.jd}`));
+          console.error(chalk7.red(`Failed to read job description file: ${options.jd}`));
           return;
         }
       }
+      const cfg = loadConfig(options.config ? { configPath: options.config } : {});
       const result = analyzeAts(resumeData, {
-        language: "en",
-        jobDescription
+        language: cfg.locale,
+        jobDescription,
+        config: cfg
       });
       if (options.format === "json") {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        formatAtsReport(result, !!options.debug, chalk6);
+        formatAtsReport(result, !!options.debug, chalk7);
       }
       const threshold = options.atsThreshold ? parseInt(options.atsThreshold, 10) : void 0;
       if (threshold !== void 0 && result.score < threshold) {
-        console.error(chalk6.red(`
+        console.error(chalk7.red(`
 ATS score ${result.score} is below threshold ${threshold}.`));
         process.exit(1);
       }
@@ -232,17 +223,17 @@ ATS score ${result.score} is below threshold ${threshold}.`));
 // src/commands/tojson.ts
 import fs4 from "fs";
 async function toJsonAction(options) {
-  const chalk6 = (await import("chalk")).default;
-  console.log(chalk6.blue("Starting resuml tojson..."));
+  const chalk7 = (await import("chalk")).default;
+  console.log(chalk7.blue("Starting resuml tojson..."));
   try {
     const inputPath = options.resume;
     const { yamlContents } = await loadResumeFiles(inputPath);
-    console.log(chalk6.blue("Processing and validating data..."));
+    console.log(chalk7.blue("Processing and validating data..."));
     const resumeData = await processResumeData(yamlContents);
-    console.log(chalk6.green("Processing and validation successful!"));
+    console.log(chalk7.green("Processing and validation successful!"));
     const jsonOutput = JSON.stringify(resumeData, null, 2);
     fs4.writeFileSync(options.output, jsonOutput, "utf8");
-    console.log(chalk6.green(`Successfully wrote output to ${options.output}`));
+    console.log(chalk7.green(`Successfully wrote output to ${options.output}`));
   } catch (error) {
     handleCommandError(error, "tojson", options.debug);
   }
@@ -454,15 +445,37 @@ async function initAction(options) {
     const name = await ask(rl, "Your full name", "John Doe");
     const email = await ask(rl, "Email address", "john@example.com");
     const label = await ask(rl, "Professional title/label", "Software Engineer");
-    const yaml = generateResumeYaml(name, email, label);
+    const yaml2 = generateResumeYaml(name, email, label);
     fs7.mkdirSync(path4.dirname(fullPath), { recursive: true });
-    fs7.writeFileSync(fullPath, yaml, "utf8");
+    fs7.writeFileSync(fullPath, yaml2, "utf8");
+    const configPath = path4.join(path4.dirname(fullPath), "resuml.config.yaml");
+    const template = `# resuml ATS configuration
+# Override defaults; everything is optional.
+# Run \`resuml ats config --print\` to see the merged effective config.
+ats:
+  weights:
+    tiers:
+      parsing: 30
+      match: 50
+      recruiter: 20
+  thresholds:
+    seniorYoeCutoff: 10
+  disable: []
+`;
+    try {
+      fs7.writeFileSync(configPath, template, { encoding: "utf8", flag: "wx" });
+      console.log(chalk3.green(`Created resuml.config.yaml`));
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
     console.log(chalk3.green(`
 \u2705 Created ${outputPath}`));
     console.log(chalk3.blue("\nNext steps:"));
     console.log(`  1. Edit ${outputPath} to fill in your details`);
     console.log("  2. Run " + chalk3.cyan("resuml validate --resume " + outputPath));
-    console.log("  3. Run " + chalk3.cyan("resuml render --resume " + outputPath + " --theme stackoverflow"));
+    console.log(
+      "  3. Run " + chalk3.cyan("resuml render --resume " + outputPath + " --theme stackoverflow")
+    );
   } finally {
     rl.close();
   }
@@ -525,6 +538,30 @@ async function pdfAction(options) {
     try {
       const page = await browser.newPage();
       await page.setContent(htmlOutput, { waitUntil: "networkidle" });
+      const bodyText = await page.evaluate(() => document.body.innerText || "");
+      const bodyWords = bodyText.trim().split(/\s+/).filter(Boolean).length;
+      const resumeContentParts = [];
+      if (resumeData.basics?.summary) resumeContentParts.push(resumeData.basics.summary);
+      for (const w of resumeData.work || []) {
+        if (w.summary) resumeContentParts.push(w.summary);
+        resumeContentParts.push(...w.highlights || []);
+      }
+      for (const p of resumeData.projects || []) {
+        if (p.description) resumeContentParts.push(p.description);
+        resumeContentParts.push(...p.highlights || []);
+      }
+      for (const s of resumeData.skills || []) {
+        if (s.name) resumeContentParts.push(s.name);
+        resumeContentParts.push(...s.keywords || []);
+      }
+      const resumeWords = resumeContentParts.join(" ").split(/\s+/).filter(Boolean).length;
+      if (resumeWords > 0 && bodyWords < resumeWords * 0.7) {
+        console.warn(
+          chalk4.yellow(
+            `pdf-text-extractable: rendered text ${bodyWords} words vs resume ${resumeWords} (under 70%). Theme may use image-based glyphs.`
+          )
+        );
+      }
       const pdfBuffer = await page.pdf({
         format,
         margin,
@@ -533,6 +570,14 @@ async function pdfAction(options) {
       });
       fs8.mkdirSync(path5.dirname(path5.resolve(outputPath)), { recursive: true });
       fs8.writeFileSync(outputPath, pdfBuffer);
+      const sizeMb = pdfBuffer.length / (1024 * 1024);
+      if (sizeMb > 2.5) {
+        console.warn(
+          chalk4.yellow(
+            `pdf-size-under-2.5mb: PDF is ${sizeMb.toFixed(2)} MB (Greenhouse limit 2.5 MB).`
+          )
+        );
+      }
       console.log(chalk4.green(`\u2705 Successfully generated ${outputPath}`));
     } finally {
       await browser.close();
@@ -552,7 +597,9 @@ function listThemes() {
   console.log(
     `  ${"Status".padEnd(10)}${"Name".padEnd(nameWidth)}${"Package".padEnd(pkgWidth)}Description`
   );
-  console.log(`  ${"\u2500".repeat(10)}${"\u2500".repeat(nameWidth)}${"\u2500".repeat(pkgWidth)}${"\u2500".repeat(30)}`);
+  console.log(
+    `  ${"\u2500".repeat(10)}${"\u2500".repeat(nameWidth)}${"\u2500".repeat(pkgWidth)}${"\u2500".repeat(30)}`
+  );
   for (const theme of KNOWN_THEMES) {
     const installed = isThemeInstalled(theme.pkg);
     const version = installed ? getInstalledVersion(theme.pkg) : null;
@@ -579,14 +626,18 @@ function installTheme(name) {
     execSync(`npm install ${pkg}`, { stdio: "inherit" });
     console.log(chalk5.green(`
 \u2705 Successfully installed ${pkg}`));
-    console.log(chalk5.blue(`
+    console.log(
+      chalk5.blue(`
 Use it with: ${chalk5.cyan(`resuml render --theme ${known?.name || name}`)}
-`));
+`)
+    );
   } catch {
     console.error(chalk5.red(`
 \u274C Failed to install ${pkg}`));
-    console.error(chalk5.yellow(`Make sure the package exists: https://www.npmjs.com/package/${pkg}
-`));
+    console.error(
+      chalk5.yellow(`Make sure the package exists: https://www.npmjs.com/package/${pkg}
+`)
+    );
   }
 }
 function themesAction(options) {
@@ -603,6 +654,32 @@ async function mcpAction() {
   await startMcpServer();
 }
 
+// src/commands/ats.ts
+import yaml from "yaml";
+import chalk6 from "chalk";
+function atsExplain(id) {
+  if (!id) {
+    console.log(listRubricMarkdown());
+    return;
+  }
+  const entry = getRubricEntry(id);
+  if (!entry) {
+    console.error(chalk6.red(`Unknown rubric id: ${id}`));
+    process.exit(1);
+    return;
+  }
+  console.log(chalk6.bold(entry.id));
+  console.log(`  Tier:        ${entry.tier}`);
+  console.log(`  Weight:      ${entry.weight}`);
+  console.log(`  Evidence:    ${entry.evidenceLevel}`);
+  console.log(`  Description: ${entry.description}`);
+  if (entry.source) console.log(`  Source:      ${entry.source}`);
+}
+function atsConfigPrint(opts) {
+  const cfg = loadConfig(opts.config ? { configPath: opts.config } : {});
+  console.log(yaml.stringify({ ats: cfg }));
+}
+
 // src/utils/themeRender.ts
 var themeRender_exports = {};
 __export(themeRender_exports, {
@@ -671,7 +748,10 @@ function getCliVersion() {
 }
 var program = new Command();
 program.name("resuml").description("CLI tool for managing resuml resume files.").version(getCliVersion());
-program.command("validate").description("Validates resume data against the schema.").option("-r, --resume <path>", "Input YAML file, directory, or glob pattern.").option("--debug", "Show detailed validation errors.").option("--ats", "Run ATS (Applicant Tracking System) compatibility analysis.").option("--jd <path>", "Path to a job description file for keyword matching (requires --ats).").option("--ats-threshold <score>", "Minimum ATS score (0-100). Exit with code 1 if below threshold.").option("--format <type>", "Output format for ATS results (text or json).", "text").action(validateAction);
+program.command("validate").description("Validates resume data against the schema.").option("-r, --resume <path>", "Input YAML file, directory, or glob pattern.").option("--debug", "Show detailed validation errors.").option("--ats", "Run ATS (Applicant Tracking System) compatibility analysis.").option("--jd <path>", "Path to a job description file for keyword matching (requires --ats).").option(
+  "--ats-threshold <score>",
+  "Minimum ATS score (0-100). Exit with code 1 if below threshold."
+).option("--format <type>", "Output format for ATS results (text or json).", "text").option("--config <path>", "Path to resuml.config.yaml (default: ./resuml.config.yaml).").action(validateAction);
 program.command("tojson").description("Converts YAML resume data to JSON format.").option("-r, --resume <path>", "Input YAML file, directory, or glob pattern.").option("-o, --output <file>", "Output JSON file path.", "resume.json").option("--debug", "Show detailed validation and processing information.").action(toJsonAction);
 program.command("render").description("Renders the resume data using a specified theme.").option("-r, --resume <path>", "Input YAML file, directory, or glob pattern.").option("-t, --theme <name>", "Theme name (e.g., stackoverflow, react).").option("-o, --output <file>", "Output file path.").option("--format <type>", "Output format (html or pdf).", "html").option("--language <code>", "Language code for localization.", "en").option("--debug", "Show detailed validation and processing information.").action(renderAction);
 program.command("dev").description("Start development server with hot-reload.").option("-r, --resume <path>", "Input YAML file, directory, or glob pattern.").option("-t, --theme <name>", "Theme name (e.g., stackoverflow, react).").option("--port <number>", "Port for development server.", "3000").option("--language <code>", "Language code for localization.", "en").option("--debug", "Show detailed validation and processing information.").action(devAction);
@@ -679,6 +759,13 @@ program.command("init").description("Scaffold a starter resume.yaml file with al
 program.command("pdf").description("Export resume as PDF using Playwright.").option("-r, --resume <path>", "Input YAML file, directory, or glob pattern.").option("-t, --theme <name>", "Theme name (e.g., stackoverflow, react).").option("-o, --output <file>", "Output PDF file path.", "resume.pdf").option("--language <code>", "Language code for localization.", "en").option("--format <size>", "Page format: A4 or Letter.", "A4").option("--margin <values>", 'Page margins (e.g., "10mm" or "10mm,15mm,10mm,15mm").').option("--debug", "Show detailed validation and processing information.").action(pdfAction);
 program.command("themes").description("List available JSON Resume themes and install them.").option("--install <name>", "Install a theme by name (e.g., stackoverflow, elegant).").action(themesAction);
 program.command("mcp").description("Start MCP server for AI agent integration (stdio transport).").action(mcpAction);
+var ats = program.command("ats").description("ATS rubric utilities.");
+ats.command("explain [id]").description("Print rubric entry for a check id, or full rubric if id omitted.").action((id) => {
+  atsExplain(id);
+});
+ats.command("config").description("Print the effective merged ATS config.").option("--print", "Print the merged config (default action).").option("--config <path>", "Path to resuml.config.yaml.").action((opts) => {
+  atsConfigPrint(opts);
+});
 if (process.env["NODE_ENV"] !== "test") {
   void (async () => {
     try {