resume-cli 3.6.0 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -25,6 +25,7 @@ npm install -g resume-cli
25
25
  | init | Initialize a `resume.json` file. |
26
26
  | validate | Schema validation test your `resume.json`. |
27
27
  | export path/to/file.html | Export to `.html`, `.pdf`, `.md` or `.txt`. |
28
+ | audit | Score your resume for ATS (Applicant Tracking System) friendliness. |
28
29
  | themes | List the JSON Resume themes installed in `node_modules`. |
29
30
  | serve | Serve resume at `http://localhost:4000/`. |
30
31
 
@@ -105,6 +106,45 @@ Options:
105
106
  - `--format <file type>` Example: `--format pdf`
106
107
  - `--theme <name>` Example: `--theme even` (only used for `.html` / `.pdf`)
107
108
 
109
+ ### `resume audit [fileName]`
110
+
111
+ Scores your resume for **ATS (Applicant Tracking System) friendliness**. It
112
+ renders your resume to HTML with a theme, runs
113
+ [`@jsonresume/ats-validator`](../ats-validator) against the markup, and prints an
114
+ advisory report: an overall score and letter grade, a per-check pass/fail
115
+ breakdown, and recommendations.
116
+
117
+ ```
118
+ $ resume audit resume.json
119
+
120
+ ATS score: 88/100 (grade B, excellent)
121
+ 9/10 checks passed, 1 need attention
122
+
123
+ Checks:
124
+ ✓ Semantic HTML (10/10)
125
+ ✓ ATS-Friendly Fonts (10/15)
126
+ ✓ No Table Layouts (15/15)
127
+ ✗ Single-Column Layout (6/15)
128
+ ✓ Heading Structure (10/10)
129
+ ...
130
+
131
+ Recommendations:
132
+ - 📋 Single-Column Layout: 6/15 - Review and fix issues in this category
133
+ - ✅ Great! Your resume is highly ATS-compatible. Minor improvements possible.
134
+ ```
135
+
136
+ The audit is **advisory** — a successful audit always exits `0` regardless of
137
+ score. It only exits non-zero when the resume can't be read or the theme can't
138
+ be rendered (the same friendly errors as `export`).
139
+
140
+ The file argument is optional; it falls back to `--resume` (default
141
+ `resume.json`). The report is rendered with the bundled `even` theme by default;
142
+ pass `--theme <name>` to audit the markup a specific theme produces.
143
+
144
+ Options:
145
+
146
+ - `--theme <name>` Example: `--theme elegant` (defaults to `even`)
147
+
108
148
  ### `resume themes`
109
149
 
110
150
  Lists the JSON Resume themes installed in `node_modules` — both in your project
@@ -0,0 +1,23 @@
1
+ "use strict";
2
+
3
+ // Adapter around the ESM-only `@jsonresume/ats-validator` package.
4
+ //
5
+ // The CLI is transpiled to CommonJS by Babel, which rewrites `import()` into a
6
+ // `require()` call. `require()` of a native ES module throws on Node < 22, so
7
+ // we reach for a real dynamic `import()` that Babel leaves untouched by hiding
8
+ // it behind the Function constructor. This keeps the audit command working
9
+ // uniformly across Node 18/20/22 without editing the validator package.
10
+ const nativeImport = new Function('specifier', 'return import(specifier)');
11
+ let cached;
12
+
13
+ // Lazily load and memoize the validator's public API
14
+ // (`validateATS` + `getRecommendations`).
15
+ const loadValidator = async () => {
16
+ if (!cached) {
17
+ cached = await nativeImport('@jsonresume/ats-validator');
18
+ }
19
+ return cached;
20
+ };
21
+ module.exports = {
22
+ loadValidator
23
+ };
package/build/audit.js ADDED
@@ -0,0 +1,96 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.formatAuditReport = exports.default = void 0;
7
+ var _chalk = _interopRequireDefault(require("chalk"));
8
+ var _renderHtml = _interopRequireDefault(require("./render-html"));
9
+ var _themeErrors = require("./theme-errors");
10
+ var _atsValidator = require("./ats-validator");
11
+ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
12
+ // Map a coarse ATS-compatibility band to a chalk colorizer so the headline
13
+ // score reads at a glance.
14
+ const colorForCompatibility = compatibility => {
15
+ switch (compatibility) {
16
+ case 'excellent':
17
+ return _chalk.default.green;
18
+ case 'good':
19
+ return _chalk.default.cyan;
20
+ case 'fair':
21
+ return _chalk.default.yellow;
22
+ default:
23
+ return _chalk.default.red;
24
+ }
25
+ };
26
+
27
+ // Build the human-readable report lines from a validateATS() result. Kept pure
28
+ // (no console / no process) so it is trivially unit-testable.
29
+ const formatAuditReport = (result, recommendations) => {
30
+ const color = colorForCompatibility(result.atsCompatibility);
31
+ const lines = [];
32
+ lines.push('');
33
+ lines.push(color(`ATS score: ${result.score}/100 (grade ${result.grade}, ${result.atsCompatibility})`));
34
+ lines.push(_chalk.default.gray(`${result.passed}/${result.checks.length} checks passed, ${result.failed} need attention`));
35
+ lines.push('');
36
+ lines.push(_chalk.default.bold('Checks:'));
37
+ result.checks.forEach(check => {
38
+ const mark = check.passed ? _chalk.default.green('✓') : _chalk.default.red('✗');
39
+ lines.push(` ${mark} ${check.name} (${check.score}/${check.maxScore})`);
40
+ });
41
+ if (recommendations.length > 0) {
42
+ lines.push('');
43
+ lines.push(_chalk.default.bold('Recommendations:'));
44
+ recommendations.forEach(rec => {
45
+ lines.push(` - ${rec}`);
46
+ });
47
+ }
48
+ lines.push('');
49
+ return lines.join('\n');
50
+ };
51
+
52
+ // Run an ATS-friendliness audit: render the resume to HTML with `themePath`,
53
+ // score it with @jsonresume/ats-validator, and print an advisory report.
54
+ //
55
+ // `resume` is an already-loaded/parsed resume object (callers reuse the shared
56
+ // loader). Render/validator failures are reported through the friendly error
57
+ // path and surfaced via a non-zero exit; a successful audit always exits 0 —
58
+ // the score is advisory, not a gate.
59
+ exports.formatAuditReport = formatAuditReport;
60
+ const audit = async ({
61
+ resume,
62
+ themePath,
63
+ log = console.log
64
+ }) => {
65
+ let html;
66
+ try {
67
+ html = await (0, _renderHtml.default)({
68
+ resume,
69
+ themePath
70
+ });
71
+ } catch (err) {
72
+ if (err instanceof _themeErrors.ThemeNotFoundError) {
73
+ console.error((0, _themeErrors.formatThemeNotFound)(err.theme));
74
+ } else {
75
+ console.error(_chalk.default.red(err && err.message ? err.message : String(err)));
76
+ }
77
+ process.exitCode = 1;
78
+ return;
79
+ }
80
+ let result;
81
+ let recommendations;
82
+ try {
83
+ const {
84
+ validateATS,
85
+ getRecommendations
86
+ } = await (0, _atsValidator.loadValidator)();
87
+ result = validateATS(html);
88
+ recommendations = getRecommendations(result);
89
+ } catch (err) {
90
+ console.error(_chalk.default.red(`Could not audit resume: ${err && err.message ? err.message : String(err)}`));
91
+ process.exitCode = 1;
92
+ return;
93
+ }
94
+ log(formatAuditReport(result, recommendations));
95
+ };
96
+ var _default = exports.default = audit;
@@ -0,0 +1,120 @@
1
+ "use strict";
2
+
3
+ var _child_process = require("child_process");
4
+ var _streamToString = _interopRequireDefault(require("stream-to-string"));
5
+ var _util = require("util");
6
+ var _package = _interopRequireDefault(require("../package.json"));
7
+ var _audit = require("./audit");
8
+ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
9
+ const exec = (0, _util.promisify)(_child_process.exec);
10
+
11
+ // Spawn the built CLI through the in-memory volume test entry (same harness as
12
+ // main.test.js) so `audit` exercises the real load -> render -> validate path.
13
+ const run = async (argv, {
14
+ captureStderr = false
15
+ } = {}) => {
16
+ let exitCode;
17
+ const child = (0, _child_process.spawn)(process.execPath, ['build/test-utils/cli-test-entry.js', ...argv], {
18
+ stdio: ['pipe', 'pipe', captureStderr ? 'pipe' : 2, 'ipc']
19
+ });
20
+ const exited = new Promise(resolve => {
21
+ child.on('exit', code => {
22
+ exitCode = code;
23
+ resolve();
24
+ });
25
+ });
26
+ child.stdin.end();
27
+ const stdout = await (0, _streamToString.default)(child.stdout);
28
+ const stderr = captureStderr ? await (0, _streamToString.default)(child.stderr) : '';
29
+ await exited;
30
+ return {
31
+ code: exitCode,
32
+ stdout,
33
+ stderr
34
+ };
35
+ };
36
+ describe('formatAuditReport', () => {
37
+ const result = {
38
+ score: 85,
39
+ grade: 'B',
40
+ atsCompatibility: 'excellent',
41
+ passed: 1,
42
+ failed: 1,
43
+ checks: [{
44
+ name: 'Semantic HTML',
45
+ score: 10,
46
+ maxScore: 10,
47
+ passed: true
48
+ }, {
49
+ name: 'Single-Column Layout',
50
+ score: 6,
51
+ maxScore: 15,
52
+ passed: false
53
+ }]
54
+ };
55
+ it('renders the headline score, grade, per-check marks and recommendations', () => {
56
+ const report = (0, _audit.formatAuditReport)(result, ['fix the layout']);
57
+ expect(report).toContain('ATS score: 85/100');
58
+ expect(report).toContain('grade B');
59
+ expect(report).toContain('1/2 checks passed');
60
+ expect(report).toContain('Semantic HTML (10/10)');
61
+ expect(report).toContain('Single-Column Layout (6/15)');
62
+ expect(report).toContain('Recommendations:');
63
+ expect(report).toContain('fix the layout');
64
+ });
65
+ it('omits the recommendations block when there are none', () => {
66
+ const report = (0, _audit.formatAuditReport)(result, []);
67
+ expect(report).not.toContain('Recommendations:');
68
+ });
69
+ });
70
+ describe('audit command', () => {
71
+ beforeAll(() => exec(_package.default.scripts.prepare));
72
+ it('prints a score and at least one recommendation for the sample resume, exit 0', async () => {
73
+ const {
74
+ code,
75
+ stdout
76
+ } = await run(['audit', '/test-resumes/resume.json',
77
+ // `even` is bundled and renders minimal resumes; the default `elegant`
78
+ // theme requires a `basics.location`.
79
+ '--theme', 'even']);
80
+ expect(code).toEqual(0);
81
+ expect(stdout).toMatch(/ATS score: \d+\/100/);
82
+ expect(stdout).toContain('grade');
83
+ expect(stdout).toContain('Checks:');
84
+ // The validator always returns at least one check; the sample resume also
85
+ // surfaces a recommendation, proving the recommendations path is wired.
86
+ expect(stdout).toContain('Recommendations:');
87
+ });
88
+ it('uses the bundled `even` theme by default (no --theme needed)', async () => {
89
+ const {
90
+ code,
91
+ stdout
92
+ } = await run(['audit', '/test-resumes/resume.json']);
93
+ expect(code).toEqual(0);
94
+ expect(stdout).toMatch(/ATS score: \d+\/100/);
95
+ });
96
+ it('prints a friendly error and exits non-zero when the resume file is missing', async () => {
97
+ const {
98
+ code,
99
+ stderr
100
+ } = await run(['audit', '/test-resumes/does-not-exist.json', '--theme', 'even'], {
101
+ captureStderr: true
102
+ });
103
+ expect(code).toEqual(1);
104
+ expect(stderr).toContain('Could not read resume: /test-resumes/does-not-exist.json');
105
+ // No raw Node unhandled-rejection stack trace must leak.
106
+ expect(stderr).not.toContain('triggerUncaughtException');
107
+ expect(stderr).not.toContain('node:internal');
108
+ });
109
+ it('prints a friendly, actionable message and exits non-zero for an uninstalled theme', async () => {
110
+ const {
111
+ code,
112
+ stderr
113
+ } = await run(['audit', '/test-resumes/resume.json', '--theme', 'nonexistent-xyz'], {
114
+ captureStderr: true
115
+ });
116
+ expect(code).toEqual(1);
117
+ expect(stderr).toContain("Theme 'nonexistent-xyz' not found.");
118
+ expect(stderr).toContain('https://jsonresume.org/themes/');
119
+ });
120
+ });
@@ -0,0 +1,28 @@
1
+ "use strict";
2
+
3
+ Object.defineProperty(exports, "__esModule", {
4
+ value: true
5
+ });
6
+ exports.default = void 0;
7
+ var _chalk = _interopRequireDefault(require("chalk"));
8
+ var _getResume = _interopRequireDefault(require("./get-resume"));
9
+ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
10
+ // Load the resume from the given path, turning the low-level failures
11
+ // (missing file, unreadable stream, malformed JSON/YAML) into a single
12
+ // friendly, stack-trace-free message. Returns null on failure after printing
13
+ // the message and flagging a non-zero exit code, so callers can bail early
14
+ // instead of leaking an unhandled rejection / Node-internal stack trace.
15
+ const loadResumeOrReport = async resumePath => {
16
+ try {
17
+ return await (0, _getResume.default)({
18
+ path: resumePath
19
+ });
20
+ } catch (err) {
21
+ const label = resumePath === '-' ? 'stdin' : resumePath;
22
+ console.error(_chalk.default.red(`Could not read resume: ${label}`));
23
+ console.error(err && err.message ? err.message : String(err));
24
+ process.exitCode = 1;
25
+ return null;
26
+ }
27
+ };
28
+ var _default = exports.default = loadResumeOrReport;
package/build/main.js CHANGED
@@ -3,9 +3,10 @@
3
3
 
4
4
  require("dotenv/config");
5
5
  var _init = _interopRequireDefault(require("./init"));
6
- var _getResume = _interopRequireDefault(require("./get-resume"));
6
+ var _loadResume = _interopRequireDefault(require("./load-resume"));
7
7
  var _getSchema = _interopRequireDefault(require("./get-schema"));
8
8
  var _validate = _interopRequireDefault(require("./validate"));
9
+ var _audit = _interopRequireDefault(require("./audit"));
9
10
  function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
10
11
  const pkg = require('../package.json');
11
12
  const exportResume = require('./export-resume');
@@ -55,12 +56,21 @@ const normalizeTheme = (value, defaultValue) => {
55
56
  });
56
57
  });
57
58
  program.command('validate').description("Validate your resume's schema").action(async () => {
58
- const resume = await (0, _getResume.default)({
59
- path: program.resume
60
- });
61
- const schema = await (0, _getSchema.default)({
62
- path: program.schema
63
- });
59
+ const resume = await (0, _loadResume.default)(program.resume);
60
+ if (resume === null) {
61
+ return;
62
+ }
63
+ let schema;
64
+ try {
65
+ schema = await (0, _getSchema.default)({
66
+ path: program.schema
67
+ });
68
+ } catch (e) {
69
+ console.error(chalk.red('Could not load schema.'));
70
+ console.error(e.message || String(e));
71
+ process.exitCode = 1;
72
+ return;
73
+ }
64
74
  try {
65
75
  await (0, _validate.default)({
66
76
  resume,
@@ -73,9 +83,10 @@ const normalizeTheme = (value, defaultValue) => {
73
83
  }
74
84
  });
75
85
  program.command('export [fileName]').description('Export locally to .html, .pdf, .md (markdown) or .txt (text). Supply a --format <file format> flag and argument to specify export format. .md and .txt need no theme; pick a theme for .html/.pdf with --theme (https://jsonresume.org/themes/).').action(async fileName => {
76
- const resume = await (0, _getResume.default)({
77
- path: program.resume
78
- });
86
+ const resume = await (0, _loadResume.default)(program.resume);
87
+ if (resume === null) {
88
+ return;
89
+ }
79
90
  exportResume({
80
91
  ...program,
81
92
  resume,
@@ -100,6 +111,22 @@ const normalizeTheme = (value, defaultValue) => {
100
111
  });
101
112
  console.log(formatThemesList(themes));
102
113
  });
114
+ program.command('audit [resumeFile]').description('Score your resume for ATS (Applicant Tracking System) friendliness: renders it with a theme to HTML, runs @jsonresume/ats-validator, and prints a score, per-check results and recommendations. Advisory only (always exits 0 on success). Pick a theme with --theme (default: even).').action(async resumeFile => {
115
+ const resume = await (0, _loadResume.default)(resumeFile || program.resume);
116
+ if (resume === null) {
117
+ return;
118
+ }
119
+ // The global `-t/--theme` option (default: elegant) is shared by every
120
+ // command, but `elegant` throws on minimal resumes. Default `audit` to
121
+ // the bundled, robust `even` theme unless the user explicitly asked for
122
+ // a theme on the command line.
123
+ const themeGiven = process.argv.some(arg => arg === '-t' || arg === '--theme');
124
+ const themePath = themeGiven ? program.theme : 'jsonresume-theme-even';
125
+ await (0, _audit.default)({
126
+ resume,
127
+ themePath
128
+ });
129
+ });
103
130
  program.command('serve').description('Serve resume at http://localhost:4000/').action(async () => {
104
131
  serve({
105
132
  ...program,
@@ -94,6 +94,14 @@ describe('cli configuration', () => {
94
94
  node_modules (the slug to pass to
95
95
  --theme). Browse the full gallery at
96
96
  https://jsonresume.org/themes/.
97
+ audit [resumeFile] Score your resume for ATS (Applicant
98
+ Tracking System) friendliness: renders it
99
+ with a theme to HTML, runs
100
+ @jsonresume/ats-validator, and prints a
101
+ score, per-check results and
102
+ recommendations. Advisory only (always
103
+ exits 0 on success). Pick a theme with
104
+ --theme (default: even).
97
105
  serve Serve resume at http://localhost:4000/
98
106
  help [command] display help for command
99
107
  "
@@ -142,6 +150,33 @@ describe('cli configuration', () => {
142
150
  "
143
151
  `);
144
152
  });
153
+ it('should print a friendly error and exit non-zero when the resume file is missing', async () => {
154
+ const {
155
+ code,
156
+ stderr
157
+ } = await run(['validate', '--resume', '/test-resumes/does-not-exist.json'], {
158
+ waitForVolumeExport: false,
159
+ captureStderr: true
160
+ });
161
+ expect(code).toEqual(1);
162
+ expect(stderr).toContain('Could not read resume: /test-resumes/does-not-exist.json');
163
+ // No raw Node unhandled-rejection stack trace must leak.
164
+ expect(stderr).not.toContain('triggerUncaughtException');
165
+ expect(stderr).not.toContain('node:internal');
166
+ });
167
+ it('should print a friendly error and exit non-zero when the resume JSON is malformed', async () => {
168
+ const {
169
+ code,
170
+ stderr
171
+ } = await run(['validate', '--resume', '/test-resumes/malformed-resume.json'], {
172
+ waitForVolumeExport: false,
173
+ captureStderr: true
174
+ });
175
+ expect(code).toEqual(1);
176
+ expect(stderr).toContain('Could not read resume: /test-resumes/malformed-resume.json');
177
+ expect(stderr).not.toContain('triggerUncaughtException');
178
+ expect(stderr).not.toContain('node:internal');
179
+ });
145
180
  });
146
181
  describe('themes', () => {
147
182
  it('lists installed themes by slug and links the gallery', async () => {
@@ -249,5 +284,19 @@ describe('cli configuration', () => {
249
284
  // The raw stack trace must not leak to the user.
250
285
  expect(stderr).not.toContain('at _default');
251
286
  });
287
+ it('should print a friendly error and exit non-zero when the resume file is missing', async () => {
288
+ const {
289
+ code,
290
+ stderr
291
+ } = await run(['export', '/test-resumes/exported-resume.html', '--resume', '/test-resumes/does-not-exist.json', '--theme', 'even'], {
292
+ waitForVolumeExport: false,
293
+ captureStderr: true
294
+ });
295
+ expect(code).toEqual(1);
296
+ expect(stderr).toContain('Could not read resume: /test-resumes/does-not-exist.json');
297
+ // No raw Node unhandled-rejection stack trace must leak.
298
+ expect(stderr).not.toContain('triggerUncaughtException');
299
+ expect(stderr).not.toContain('node:internal');
300
+ });
252
301
  });
253
302
  });
@@ -19,6 +19,8 @@ module.exports = ({
19
19
  name: 123
20
20
  }
21
21
  }),
22
+ // Syntactically broken JSON — exercises the parse-error path.
23
+ 'malformed-resume.json': '{ "basics": { "name": "x" ',
22
24
  'resume.json': JSON.stringify({
23
25
  basics: {
24
26
  name: 'thomas',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "resume-cli",
3
- "version": "3.6.0",
3
+ "version": "3.7.0",
4
4
  "description": "The JSON Resume command line interface",
5
5
  "main": "build/main.js",
6
6
  "engines": {
@@ -41,7 +41,8 @@
41
41
  "superagent": "^6.0.0",
42
42
  "yaml-js": "^0.2.3",
43
43
  "yesno": "^0.3.1",
44
- "@jsonresume/schema": "1.2.1"
44
+ "@jsonresume/schema": "1.3.0",
45
+ "@jsonresume/ats-validator": "0.2.0"
45
46
  },
46
47
  "devDependencies": {
47
48
  "@babel/cli": "^7.25.0",