resume-cli 3.4.0 → 3.6.0

package/README.md

@@ -25,6 +25,7 @@ npm install -g resume-cli
 | init | Initialize a `resume.json` file. |
 | validate | Schema validation test your `resume.json`. |
 | export path/to/file.html | Export to `.html`, `.pdf`, `.md` or `.txt`. |
+| themes | List the JSON Resume themes installed in `node_modules`. |
 | serve | Serve resume at `http://localhost:4000/`. |
 
 ### `resume --help`
@@ -39,7 +40,35 @@ Complete the `resume.json` with your text editor. Be sure to follow the schema (
 
 ### `resume validate`
 
-Validates your `resume.json` against our schema to ensure it complies with the standard. Tries to identify where any errors may be occurring.
+Validates your `resume.json` against our schema to ensure it complies with the standard.
+
+On success it prints a one-line summary with the candidate name and a count of
+each populated section:
+
+```
+✓ resume.json is valid (Ada Lovelace — 1 work, 1 education, 2 skills)
+```
+
+On failure it exits non-zero and prints one annotated block per problem, naming
+the exact JSON path, the failing rule, the offending value, and a one-line hint:
+
+```
+Invalid resume: 2 problems found
+
+  ✖ data/basics/email must match format "email"
+    at:    basics.email
+    rule:  format (expected email)
+    found: "nope" (string)
+    hint:  "basics.email" must be a valid email address, e.g. "you@example.com".
+
+  ✖ data/work/0/startDate must match pattern "..."
+    at:    work[0].startDate
+    rule:  pattern
+    found: "13-2020" (string)
+    hint:  "work[0].startDate" must be an ISO-8601 date: YYYY, YYYY-MM, or YYYY-MM-DD.
+```
+
+Validate against a custom schema with `--schema <path>`.
 
 ### `resume export [fileName]`
 
@@ -76,6 +105,27 @@ Options:
 - `--format <file type>` Example: `--format pdf`
 - `--theme <name>` Example: `--theme even` (only used for `.html` / `.pdf`)
 
+### `resume themes`
+
+Lists the JSON Resume themes installed in `node_modules` — both in your project
+and globally — so you don't have to know a theme slug ahead of time. It prints
+the slug to pass to `--theme` for `export` / `serve`:
+
+```
+$ resume themes
+Installed themes (2) — pass the slug to --theme:
+  elegant v1.16.1
+  even    v0.6.0
+
+Use it:         resume export resume.html --theme elegant
+Browse the full gallery:  https://jsonresume.org/themes/
+```
+
+If none are installed yet, it points you at how to install one. Discovery is
+local and network-free; browse the full gallery (with screenshots) at
+https://jsonresume.org/themes/ and `npm install jsonresume-theme-<slug>` the one
+you want.
+
 ### `resume serve`
 
 Starts a web server that serves your local `resume.json`. It will live reload when you make changes to your `resume.json`.

package/build/list-themes.js

@@ -0,0 +1,139 @@
+"use strict";
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const THEME_PREFIX = 'jsonresume-theme-';
+
+// Read a theme package's `package.json` (best effort). Returns null if the
+// directory is not a readable npm package — keeps discovery dependency-free
+// and resilient to half-installed/broken folders.
+const readThemePkg = themeDir => {
+  try {
+    const raw = fs.readFileSync(path.join(themeDir, 'package.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    return null;
+  }
+};
+
+// List the immediate child directories of a node_modules folder that look like
+// JSON Resume theme packages (`jsonresume-theme-*`). Returns one entry per
+// theme with its slug (the name passed to `--theme`), full package name,
+// version and description. Missing/unreadable folders yield an empty list.
+const listThemesInDir = nodeModulesDir => {
+  let entries;
+  try {
+    entries = fs.readdirSync(nodeModulesDir, {
+      withFileTypes: true
+    });
+  } catch (err) {
+    return [];
+  }
+  const themes = [];
+  for (const entry of entries) {
+    // Tolerate environments where `withFileTypes` is unavailable.
+    const name = entry.name || entry;
+    if (typeof name !== 'string' || !name.startsWith(THEME_PREFIX)) {
+      continue;
+    }
+    // Ignore the prefix itself with nothing after it.
+    const slug = name.slice(THEME_PREFIX.length);
+    if (!slug) {
+      continue;
+    }
+    const pkg = readThemePkg(path.join(nodeModulesDir, name));
+    if (!pkg) {
+      continue;
+    }
+    themes.push({
+      slug,
+      name,
+      version: typeof pkg.version === 'string' ? pkg.version : null,
+      description: typeof pkg.description === 'string' ? pkg.description : null
+    });
+  }
+  return themes;
+};
+
+// Build the list of `node_modules` directories to scan: every `node_modules`
+// from `cwd` up to the filesystem root (covers local + monorepo installs),
+// plus any directories supplied via `extraNodeModules` (e.g. the global root).
+const candidateNodeModules = (cwd, extraNodeModules) => {
+  const dirs = [];
+  let current = path.resolve(cwd);
+  // Walk up the tree collecting node_modules at each level.
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    dirs.push(path.join(current, 'node_modules'));
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  for (const extra of extraNodeModules) {
+    if (extra) {
+      dirs.push(extra);
+    }
+  }
+  return dirs;
+};
+
+// Discover installed JSON Resume themes.
+//
+// Scans `node_modules` from the current working directory up the tree plus any
+// `extraNodeModules` (the global install root by default) for
+// `jsonresume-theme-*` packages. Returns a list of unique themes sorted by
+// slug. The first occurrence of a slug wins, so a project-local install
+// shadows a global one — matching how `require.resolve` would pick a theme.
+//
+// Pure and network-free: callers inject `cwd` and `extraNodeModules` in tests.
+const discoverThemes = ({
+  cwd = process.cwd(),
+  extraNodeModules = []
+} = {}) => {
+  const seen = new Set();
+  const themes = [];
+  for (const dir of candidateNodeModules(cwd, extraNodeModules)) {
+    for (const theme of listThemesInDir(dir)) {
+      if (seen.has(theme.slug)) {
+        continue;
+      }
+      seen.add(theme.slug);
+      themes.push(theme);
+    }
+  }
+  themes.sort((a, b) => a.slug.localeCompare(b.slug));
+  return themes;
+};
+
+// Render the discovered themes as a clean, copy-pasteable block. Each line
+// shows the slug to pass to `--theme`. When nothing is installed we point the
+// user at how to install a theme; either way we link the full gallery.
+const formatThemesList = themes => {
+  const lines = [];
+  if (themes.length === 0) {
+    lines.push(chalk.yellow('No JSON Resume themes found in node_modules.'));
+    lines.push(`Install one:    ${chalk.cyan('npm install jsonresume-theme-even')}`);
+  } else {
+    const count = themes.length;
+    lines.push(chalk.bold(`Installed themes (${count}) — pass the slug to ${chalk.cyan('--theme')}:`));
+    const width = themes.reduce((max, t) => Math.max(max, t.slug.length), 0);
+    for (const theme of themes) {
+      const slug = chalk.green(theme.slug.padEnd(width));
+      const version = theme.version ? chalk.dim(` v${theme.version}`) : '';
+      lines.push(`  ${slug}${version}`);
+    }
+    lines.push('');
+    lines.push(`Use it:         ${chalk.cyan(`resume export resume.html --theme ${themes[0].slug}`)}`);
+  }
+  lines.push(`Browse the full gallery:  ${chalk.cyan('https://jsonresume.org/themes/')}`);
+  return lines.join('\n');
+};
+module.exports = {
+  THEME_PREFIX,
+  discoverThemes,
+  listThemesInDir,
+  formatThemesList
+};

package/build/list-themes.test.js

@@ -0,0 +1,168 @@
+"use strict";
+
+var _fs = _interopRequireDefault(require("fs"));
+var _os = _interopRequireDefault(require("os"));
+var _path = _interopRequireDefault(require("path"));
+var _listThemes = require("./list-themes");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Build a throwaway project directory on the real filesystem whose
+// `node_modules` mirrors a typical install: a couple of real themes, a broken
+// theme folder (no package.json), and unrelated packages that must be ignored.
+const buildFixtureProject = () => {
+  const root = _fs.default.mkdtempSync(_path.default.join(_os.default.tmpdir(), 'resume-cli-themes-'));
+  const nodeModules = _path.default.join(root, 'node_modules');
+  const writePkg = (dirName, pkg) => {
+    const dir = _path.default.join(nodeModules, dirName);
+    _fs.default.mkdirSync(dir, {
+      recursive: true
+    });
+    if (pkg) {
+      _fs.default.writeFileSync(_path.default.join(dir, 'package.json'), JSON.stringify(pkg));
+    }
+  };
+
+  // Two valid themes (out of alphabetical order to prove sorting).
+  writePkg('jsonresume-theme-even', {
+    name: 'jsonresume-theme-even',
+    version: '0.6.0',
+    description: 'A flat JSON Resume theme.'
+  });
+  writePkg('jsonresume-theme-elegant', {
+    name: 'jsonresume-theme-elegant',
+    version: '1.16.1'
+  });
+  // A theme-prefixed folder with no package.json — half-installed/broken;
+  // must be skipped, not crash discovery.
+  writePkg('jsonresume-theme-broken', null);
+  // Non-theme packages that must never appear in the list.
+  writePkg('chalk', {
+    name: 'chalk',
+    version: '4.1.0'
+  });
+  writePkg('jsonresume-other', {
+    name: 'jsonresume-other',
+    version: '1.0.0'
+  });
+  return {
+    root,
+    nodeModules
+  };
+};
+describe('list-themes discovery', () => {
+  let fixture;
+  beforeAll(() => {
+    fixture = buildFixtureProject();
+  });
+  afterAll(() => {
+    _fs.default.rmSync(fixture.root, {
+      recursive: true,
+      force: true
+    });
+  });
+  it('lists installed jsonresume-theme-* packages by slug, sorted', () => {
+    const themes = (0, _listThemes.discoverThemes)({
+      cwd: fixture.root
+    });
+    expect(themes.map(t => t.slug)).toEqual(['elegant', 'even']);
+  });
+  it('ignores non-theme packages and broken theme folders', () => {
+    const slugs = (0, _listThemes.discoverThemes)({
+      cwd: fixture.root
+    }).map(t => t.slug);
+    expect(slugs).not.toContain('broken');
+    expect(slugs).not.toContain('other');
+    expect(slugs).not.toContain('chalk');
+  });
+  it('captures the package name, version and description of each theme', () => {
+    const themes = (0, _listThemes.discoverThemes)({
+      cwd: fixture.root
+    });
+    const even = themes.find(t => t.slug === 'even');
+    expect(even).toEqual({
+      slug: 'even',
+      name: 'jsonresume-theme-even',
+      version: '0.6.0',
+      description: 'A flat JSON Resume theme.'
+    });
+    // A theme without a description still resolves, with description null.
+    const elegant = themes.find(t => t.slug === 'elegant');
+    expect(elegant.version).toEqual('1.16.1');
+    expect(elegant.description).toBeNull();
+  });
+  it('returns an empty list when node_modules is missing', () => {
+    const empty = _fs.default.mkdtempSync(_path.default.join(_os.default.tmpdir(), 'resume-cli-empty-'));
+    try {
+      expect((0, _listThemes.discoverThemes)({
+        cwd: empty
+      })).toEqual([]);
+    } finally {
+      _fs.default.rmSync(empty, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+  it('de-duplicates a slug installed in multiple node_modules (local wins)', () => {
+    // A second node_modules (e.g. a global root) also ships `even`, plus a
+    // theme not present locally. The local `even` should win; `global-only`
+    // should be added.
+    const globalRoot = _fs.default.mkdtempSync(_path.default.join(_os.default.tmpdir(), 'resume-cli-global-'));
+    try {
+      const writeGlobalPkg = (dirName, pkg) => {
+        const dir = _path.default.join(globalRoot, dirName);
+        _fs.default.mkdirSync(dir, {
+          recursive: true
+        });
+        _fs.default.writeFileSync(_path.default.join(dir, 'package.json'), JSON.stringify(pkg));
+      };
+      writeGlobalPkg('jsonresume-theme-even', {
+        name: 'jsonresume-theme-even',
+        version: '9.9.9'
+      });
+      writeGlobalPkg('jsonresume-theme-global-only', {
+        name: 'jsonresume-theme-global-only',
+        version: '2.0.0'
+      });
+      const themes = (0, _listThemes.discoverThemes)({
+        cwd: fixture.root,
+        extraNodeModules: [globalRoot]
+      });
+      const slugs = themes.map(t => t.slug);
+      expect(slugs).toEqual(['elegant', 'even', 'global-only']);
+      // Local install shadows the global one (version stays 0.6.0).
+      expect(themes.find(t => t.slug === 'even').version).toEqual('0.6.0');
+    } finally {
+      _fs.default.rmSync(globalRoot, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+  it('listThemesInDir returns [] for a non-existent directory', () => {
+    expect((0, _listThemes.listThemesInDir)('/no/such/dir/node_modules')).toEqual([]);
+  });
+});
+describe('formatThemesList', () => {
+  it('prints each slug and a usage example when themes are installed', () => {
+    const output = (0, _listThemes.formatThemesList)([{
+      slug: 'elegant',
+      name: 'jsonresume-theme-elegant',
+      version: '1.16.1'
+    }, {
+      slug: 'even',
+      name: 'jsonresume-theme-even',
+      version: '0.6.0'
+    }]);
+    expect(output).toContain('Installed themes (2)');
+    expect(output).toContain('elegant');
+    expect(output).toContain('even');
+    expect(output).toContain('--theme elegant');
+    expect(output).toContain('https://jsonresume.org/themes/');
+  });
+  it('prints an install hint and the gallery link when nothing is installed', () => {
+    const output = (0, _listThemes.formatThemesList)([]);
+    expect(output).toContain('No JSON Resume themes found');
+    expect(output).toContain('npm install jsonresume-theme-even');
+    expect(output).toContain('https://jsonresume.org/themes/');
+  });
+});

package/build/main.js

@@ -17,6 +17,28 @@ const {
   ThemeNotFoundError,
   formatThemeNotFound
 } = require('./theme-errors');
+const {
+  formatOkSummary
+} = require('./validate-errors');
+const {
+  discoverThemes,
+  formatThemesList
+} = require('./list-themes');
+
+// Best-effort guess at the global `node_modules` root so `resume themes` also
+// surfaces globally-installed themes (e.g. `npm install -g`). Derived from the
+// node executable path; no network or extra dependency required.
+const globalNodeModules = () => {
+  try {
+    // <prefix>/bin/node -> <prefix>/lib/node_modules (POSIX),
+    // <prefix>/node.exe -> <prefix>/node_modules (Windows).
+    const binDir = path.dirname(process.execPath);
+    const candidates = [path.join(binDir, '..', 'lib', 'node_modules'), path.join(binDir, 'node_modules')];
+    return candidates;
+  } catch (err) {
+    return [];
+  }
+};
 const normalizeTheme = (value, defaultValue) => {
   const theme = value || defaultValue;
   // TODO - This is not great, but bypasses this function if it is a relative path
@@ -44,9 +66,9 @@ const normalizeTheme = (value, defaultValue) => {
         resume,
         schema
       });
-      console.log(chalk.green(`✓ ${program.resume} is valid`));
+      console.log(chalk.green(formatOkSummary(resume, program.resume)));
     } catch (e) {
-      console.error(e.message);
+      console.error(chalk.red(e.message));
       process.exitCode = 1;
     }
   });
@@ -71,6 +93,13 @@ const normalizeTheme = (value, defaultValue) => {
       console.log(chalk.green('\nDone! Find your new', format, 'resume at:\n', path.resolve(process.cwd(), fileName + format)));
     });
   });
+  program.command('themes').description('List JSON Resume themes installed in node_modules (the slug to pass to --theme). Browse the full gallery at https://jsonresume.org/themes/.').action(async () => {
+    const themes = discoverThemes({
+      cwd: process.cwd(),
+      extraNodeModules: globalNodeModules()
+    });
+    console.log(formatThemesList(themes));
+  });
   program.command('serve').description('Serve resume at http://localhost:4000/').action(async () => {
     serve({
       ...program,

package/build/main.test.js

@@ -90,6 +90,10 @@ describe('cli configuration', () => {
                                             need no theme; pick a theme for
                                             .html/.pdf with --theme
                                             (https://jsonresume.org/themes/).
+        themes                              List JSON Resume themes installed in
+                                            node_modules (the slug to pass to
+                                            --theme). Browse the full gallery at
+                                            https://jsonresume.org/themes/.
         serve                               Serve resume at http://localhost:4000/
         help [command]                      display help for command
       "
@@ -108,7 +112,7 @@ describe('cli configuration', () => {
     it('should fail when trying to validate an invalid resume specified by the --resume option', async () => {
       expect((await run(['validate', '--resume', '/test-resumes/invalid-resume.json'])).code).toEqual(1);
     });
-    it('should print the per-field error list (not a success line) when validation fails', async () => {
+    it('should print precise, path-pointed errors (not a success line) when validation fails', async () => {
       const {
         code,
         stdout,
@@ -119,7 +123,13 @@ describe('cli configuration', () => {
       });
       expect(code).toEqual(1);
       expect(stderr).toContain('Invalid resume:');
+      // The classic data-path phrasing is preserved...
       expect(stderr).toContain('data/basics/name must be string');
+      // ...alongside the new annotated path/rule/value/hint lines.
+      expect(stderr).toContain('at:    basics.name');
+      expect(stderr).toContain('rule:  type (expected string)');
+      expect(stderr).toContain('found: 123 (number)');
+      expect(stderr).toContain('must be of type string');
       // The success line must not appear for an invalid resume.
       expect(stdout).not.toContain('is valid');
     });
@@ -128,11 +138,28 @@ describe('cli configuration', () => {
         stdout
       } = await run(['validate', '--resume', '/test-resumes/resume.json']);
       expect(stdout).toMatchInlineSnapshot(`
-        "✓ /test-resumes/resume.json is valid
+        "✓ /test-resumes/resume.json is valid (thomas)
         "
       `);
     });
   });
+  describe('themes', () => {
+    it('lists installed themes by slug and links the gallery', async () => {
+      const {
+        stdout,
+        code
+      } = await run(['themes'], {
+        waitForVolumeExport: false
+      });
+      expect(code).toEqual(0);
+      // The CLI bundles the `elegant` and `even` themes as dependencies, so
+      // they are always discoverable from the package's node_modules.
+      expect(stdout).toContain('elegant');
+      expect(stdout).toContain('even');
+      expect(stdout).toContain('--theme');
+      expect(stdout).toContain('https://jsonresume.org/themes/');
+    });
+  });
   describe('export', () => {
     it('should read from stdin when path is a dash', async () => {
       const {

package/build/validate-errors.js

@@ -0,0 +1,192 @@
+"use strict";
+
+// Turns raw Ajv (draft-07) error objects into precise, actionable output.
+//
+// For each failure we surface four things:
+//   - the JSON path in dot/bracket notation (e.g. work[2].startDate)
+//   - the failing rule (the Ajv keyword, lightly humanised)
+//   - the offending value (with its JS type)
+//   - a one-line, human hint on how to fix it
+//
+// The first physical line of each error is kept as `<dataPath> <message>`
+// (e.g. `data/basics/name must be string`) so existing tooling that greps the
+// output for that classic phrasing keeps working.
+
+// "/work/1/startDate" -> "work[1].startDate"; the root is "(root)".
+const toDotPath = instancePath => {
+  if (!instancePath) {
+    return '(root)';
+  }
+  const segments = instancePath.split('/').filter(Boolean);
+  return segments.map(segment => /^\d+$/.test(segment) ? `[${segment}]` : `.${segment}`).join('').replace(/^\./, '');
+};
+
+// "data" + instancePath, matching Ajv's classic dataPath phrasing.
+const toDataPath = instancePath => instancePath ? `data${instancePath}` : 'data';
+const previewValue = value => {
+  if (value === undefined) {
+    return 'undefined';
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(value);
+  } catch {
+    serialised = String(value);
+  }
+  if (serialised === undefined) {
+    serialised = String(value);
+  }
+  if (serialised.length > 80) {
+    serialised = `${serialised.slice(0, 77)}...`;
+  }
+  const type = Array.isArray(value) ? 'array' : typeof value;
+  return `${serialised} (${type})`;
+};
+
+// Resolve the value the error points at by walking the instancePath.
+const valueAtPath = (root, instancePath) => {
+  if (!instancePath) {
+    return root;
+  }
+  const segments = instancePath.split('/').filter(Boolean);
+  let current = root;
+  for (const segment of segments) {
+    if (current == null) {
+      return undefined;
+    }
+    // Ajv JSON-pointer-escapes "/" as "~1" and "~" as "~0".
+    const key = segment.replace(/~1/g, '/').replace(/~0/g, '~');
+    current = current[key];
+  }
+  return current;
+};
+
+// Map an Ajv keyword to a short human description of the rule it enforces.
+const describeRule = error => {
+  const {
+    keyword,
+    params
+  } = error;
+  switch (keyword) {
+    case 'type':
+      return `type (expected ${params.type})`;
+    case 'format':
+      return `format (expected ${params.format})`;
+    case 'pattern':
+      return 'pattern';
+    case 'required':
+      return `required (${params.missingProperty})`;
+    case 'additionalProperties':
+      return `additionalProperties (${params.additionalProperty})`;
+    case 'enum':
+      return `enum (one of ${JSON.stringify(params.allowedValues)})`;
+    case 'minimum':
+    case 'maximum':
+    case 'minLength':
+    case 'maxLength':
+    case 'minItems':
+    case 'maxItems':
+      return `${keyword} (${params.limit})`;
+    default:
+      return keyword;
+  }
+};
+
+// A short, plain-language fix for the failing field.
+const hintFor = (error, dotPath) => {
+  const field = dotPath === '(root)' ? 'the resume' : `"${dotPath}"`;
+  const {
+    keyword,
+    params
+  } = error;
+  switch (keyword) {
+    case 'type':
+      return `${field} must be of type ${params.type}.`;
+    case 'format':
+      if (params.format === 'email') {
+        return `${field} must be a valid email address, e.g. "you@example.com".`;
+      }
+      if (params.format === 'uri') {
+        return `${field} must be a full URL, e.g. "https://example.com".`;
+      }
+      if (params.format === 'date') {
+        return `${field} must be an ISO date, e.g. "2024-01-31".`;
+      }
+      return `${field} must match the "${params.format}" format.`;
+    case 'pattern':
+      // The JSON Resume date fields share one ISO-8601 pattern.
+      if (/iso8601/.test(error.schemaPath || '')) {
+        return `${field} must be an ISO-8601 date: YYYY, YYYY-MM, or YYYY-MM-DD.`;
+      }
+      return `${field} does not match the required pattern.`;
+    case 'required':
+      return `add the missing "${params.missingProperty}" property to ${field}.`;
+    case 'additionalProperties':
+      return `remove the unknown property "${params.additionalProperty}" from ${field} (or check for a typo).`;
+    case 'enum':
+      return `${field} must be one of: ${params.allowedValues.map(v => JSON.stringify(v)).join(', ')}.`;
+    case 'minLength':
+      return `${field} must be at least ${params.limit} character(s) long.`;
+    case 'maxLength':
+      return `${field} must be at most ${params.limit} character(s) long.`;
+    case 'minItems':
+      return `${field} must contain at least ${params.limit} item(s).`;
+    case 'minimum':
+      return `${field} must be >= ${params.limit}.`;
+    case 'maximum':
+      return `${field} must be <= ${params.limit}.`;
+    default:
+      return `${field} ${error.message}.`;
+  }
+};
+
+// Format a single Ajv error into a multi-line, annotated block.
+const formatSingleError = (error, root) => {
+  const dataPath = toDataPath(error.instancePath);
+  const dotPath = toDotPath(error.instancePath);
+  // For `required`/`additionalProperties` the offending value is the *parent*
+  // object; show that, since the named property itself is missing/extra.
+  const value = valueAtPath(root, error.instancePath);
+  const lines = [
+  // Kept verbatim so `data/basics/name must be string`-style greps work.
+  `✖ ${dataPath} ${error.message}`, `    at:    ${dotPath}`, `    rule:  ${describeRule(error)}`];
+  if (error.keyword !== 'required') {
+    lines.push(`    found: ${previewValue(value)}`);
+  }
+  lines.push(`    hint:  ${hintFor(error, dotPath)}`);
+  return lines.join('\n');
+};
+
+// Public: build the full failure message.
+//   formatErrors(ajvErrors, resume) -> string
+const formatErrors = (errors = [], root) => {
+  const count = errors.length;
+  const heading = count === 1 ? 'Invalid resume: 1 problem found' : `Invalid resume: ${count} problems found`;
+  const blocks = errors.map(error => formatSingleError(error, root));
+  return `${heading}\n\n  ${blocks.join('\n\n  ')}`;
+};
+
+// Build a one-line OK summary that counts the populated array sections.
+const formatOkSummary = (resume, label) => {
+  const sections = ['work', 'volunteer', 'education', 'awards', 'certificates', 'publications', 'skills', 'languages', 'interests', 'references', 'projects'];
+  const counts = sections.filter(key => Array.isArray(resume && resume[key]) && resume[key].length).map(key => `${resume[key].length} ${key}`);
+  const name = resume && resume.basics && typeof resume.basics.name === 'string' ? resume.basics.name : null;
+  const parts = [];
+  if (name) {
+    parts.push(name);
+  }
+  if (counts.length) {
+    parts.push(counts.join(', '));
+  }
+  const detail = parts.length ? ` (${parts.join(' — ')})` : '';
+  const subject = label ? `${label} is valid` : 'resume is valid';
+  return `✓ ${subject}${detail}`;
+};
+module.exports = {
+  formatErrors,
+  formatOkSummary,
+  // exported for unit testing of the path/value/hint helpers
+  toDotPath,
+  previewValue,
+  hintFor
+};

package/build/validate-errors.test.js

@@ -0,0 +1,150 @@
+"use strict";
+
+const {
+  formatErrors,
+  formatOkSummary,
+  toDotPath,
+  previewValue
+} = require('./validate-errors');
+
+// A representative slice of real Ajv (draft-07) error objects, as produced by
+// `ajv.compile(schema)` against a resume with several distinct violations.
+const sampleAjvErrors = [{
+  instancePath: '/basics/name',
+  schemaPath: '#/properties/basics/properties/name/type',
+  keyword: 'type',
+  params: {
+    type: 'string'
+  },
+  message: 'must be string'
+}, {
+  instancePath: '/basics/email',
+  schemaPath: '#/properties/basics/properties/email/format',
+  keyword: 'format',
+  params: {
+    format: 'email'
+  },
+  message: 'must match format "email"'
+}, {
+  instancePath: '/work/2/startDate',
+  schemaPath: '#/definitions/iso8601/pattern',
+  keyword: 'pattern',
+  params: {
+    pattern: '^(...)$'
+  },
+  message: 'must match pattern "..."'
+}];
+const sampleResume = {
+  basics: {
+    name: 123,
+    email: 'not-an-email'
+  },
+  work: [{}, {}, {
+    startDate: '13-2020'
+  }]
+};
+describe('toDotPath', () => {
+  it('converts a JSON pointer to dot/bracket notation', () => {
+    expect(toDotPath('/work/2/startDate')).toBe('work[2].startDate');
+    expect(toDotPath('/basics/name')).toBe('basics.name');
+  });
+  it('labels the document root', () => {
+    expect(toDotPath('')).toBe('(root)');
+  });
+});
+describe('previewValue', () => {
+  it('shows the value with its JS type', () => {
+    expect(previewValue(123)).toBe('123 (number)');
+    expect(previewValue('hi')).toBe('"hi" (string)');
+    expect(previewValue([1, 2])).toBe('[1,2] (array)');
+  });
+  it('reports undefined for missing values', () => {
+    expect(previewValue(undefined)).toBe('undefined');
+  });
+});
+describe('formatErrors', () => {
+  const output = formatErrors(sampleAjvErrors, sampleResume);
+  it('counts the problems in the heading', () => {
+    expect(output).toContain('Invalid resume: 3 problems found');
+  });
+  it('names the right JSON path for each error', () => {
+    expect(output).toContain('at:    basics.name');
+    expect(output).toContain('at:    basics.email');
+    expect(output).toContain('at:    work[2].startDate');
+  });
+  it('reports the failing rule', () => {
+    expect(output).toContain('rule:  type (expected string)');
+    expect(output).toContain('rule:  format (expected email)');
+    expect(output).toContain('rule:  pattern');
+  });
+  it('shows the offending value with its type', () => {
+    expect(output).toContain('found: 123 (number)');
+    expect(output).toContain('found: "not-an-email" (string)');
+    expect(output).toContain('found: "13-2020" (string)');
+  });
+  it('gives a one-line human hint per error', () => {
+    expect(output).toContain('"basics.name" must be of type string.');
+    expect(output).toContain('must be a valid email address');
+    expect(output).toContain('must be an ISO-8601 date');
+  });
+  it('preserves the classic data-path phrasing for greppability', () => {
+    expect(output).toContain('data/basics/name must be string');
+  });
+  it('uses the singular "problem" for a single error', () => {
+    const single = formatErrors([sampleAjvErrors[0]], sampleResume);
+    expect(single).toContain('Invalid resume: 1 problem found');
+  });
+  it('handles required + additionalProperties without throwing', () => {
+    const out = formatErrors([{
+      instancePath: '/work/0',
+      schemaPath: '#/.../required',
+      keyword: 'required',
+      params: {
+        missingProperty: 'name'
+      },
+      message: "must have required property 'name'"
+    }, {
+      instancePath: '/basics',
+      schemaPath: '#/.../additionalProperties',
+      keyword: 'additionalProperties',
+      params: {
+        additionalProperty: 'nme'
+      },
+      message: 'must NOT have additional properties'
+    }], {
+      work: [{}],
+      basics: {
+        nme: 'x'
+      }
+    });
+    expect(out).toContain('rule:  required (name)');
+    expect(out).toContain('add the missing "name" property');
+    expect(out).toContain('rule:  additionalProperties (nme)');
+    expect(out).toContain('remove the unknown property "nme"');
+  });
+});
+describe('formatOkSummary', () => {
+  it('summarises populated array sections and the candidate name', () => {
+    const summary = formatOkSummary({
+      basics: {
+        name: 'Thomas'
+      },
+      work: [{}, {}],
+      education: [{}],
+      skills: [{}, {}, {}]
+    }, 'resume.json');
+    expect(summary).toContain('✓ resume.json is valid');
+    expect(summary).toContain('Thomas');
+    expect(summary).toContain('2 work');
+    expect(summary).toContain('1 education');
+    expect(summary).toContain('3 skills');
+  });
+  it('omits the detail block when there is nothing to count', () => {
+    expect(formatOkSummary({
+      basics: {}
+    }, 'resume.json')).toBe('✓ resume.json is valid');
+  });
+  it('handles a non-object resume (custom schema override)', () => {
+    expect(formatOkSummary(123, 'only-number.json')).toBe('✓ only-number.json is valid');
+  });
+});

package/build/validate.js

@@ -6,16 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _ajv = _interopRequireDefault(require("ajv"));
 var _ajvFormats = _interopRequireDefault(require("ajv-formats"));
+var _validateErrors = require("./validate-errors");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// Format a single Ajv error into a readable `field message` line.
-const formatError = error => {
-  // instancePath is like "/basics/name"; the root is an empty string.
-  const field = error.instancePath ? `data${error.instancePath}` : 'data';
-  if (error.keyword === 'additionalProperties') {
-    return `${field} ${error.message} (${error.params.additionalProperty})`;
-  }
-  return `${field} ${error.message}`;
-};
 var _default = async ({
   resume,
   schema
@@ -32,7 +24,9 @@ var _default = async ({
   if (validateFn(resume)) {
     return true;
   }
-  const details = (validateFn.errors || []).map(formatError).join('\n  ');
-  throw new Error(`Invalid resume:\n  ${details}`);
+  const error = new Error((0, _validateErrors.formatErrors)(validateFn.errors || [], resume));
+  // Expose the raw Ajv errors so callers can build machine-readable output.
+  error.validationErrors = validateFn.errors || [];
+  throw error;
 };
 exports.default = _default;

package/build/validate.test.js

@@ -16,7 +16,7 @@ describe('validate', () => {
       schema: defaultSchema
     });
   });
-  it('should throw a per-field error for an invalid resume object', async () => {
+  it('should throw a precise, path-pointed error for an invalid resume object', async () => {
     await expect((0, _validate.default)({
       resume: {
         basics: {
@@ -25,10 +25,55 @@ describe('validate', () => {
       },
       schema: defaultSchema
     })).rejects.toMatchInlineSnapshot(`
-      [Error: Invalid resume:
-        data/basics/name must be string]
+      [Error: Invalid resume: 1 problem found
+
+        ✖ data/basics/name must be string
+          at:    basics.name
+          rule:  type (expected string)
+          found: 123 (number)
+          hint:  "basics.name" must be of type string.]
     `);
   });
+  it('should report every distinct violation with its own JSON path', async () => {
+    let thrown;
+    try {
+      await (0, _validate.default)({
+        resume: {
+          basics: {
+            name: 123,
+            email: 'not-an-email'
+          },
+          work: [{
+            name: 'Acme',
+            startDate: '13-2020'
+          }]
+        },
+        schema: defaultSchema
+      });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeDefined();
+    expect(thrown.message).toContain('Invalid resume: 3 problems found');
+    // Each error names the right JSON path in dot/bracket notation.
+    expect(thrown.message).toContain('at:    basics.name');
+    expect(thrown.message).toContain('at:    basics.email');
+    expect(thrown.message).toContain('at:    work[0].startDate');
+    // ...the failing rule...
+    expect(thrown.message).toContain('rule:  type (expected string)');
+    expect(thrown.message).toContain('rule:  format (expected email)');
+    // ...the offending value...
+    expect(thrown.message).toContain('found: 123 (number)');
+    expect(thrown.message).toContain('found: "not-an-email" (string)');
+    // ...and a human hint.
+    expect(thrown.message).toContain('must be a valid email address');
+    expect(thrown.message).toContain('must be an ISO-8601 date');
+    // The classic `data/...` phrasing is preserved for greppability.
+    expect(thrown.message).toContain('data/basics/name must be string');
+    // Raw Ajv errors are exposed for machine-readable callers.
+    expect(Array.isArray(thrown.validationErrors)).toBe(true);
+    expect(thrown.validationErrors).toHaveLength(3);
+  });
   it('should accept a schema override', async () => {
     await (0, _validate.default)({
       resume: 123,
@@ -42,8 +87,13 @@ describe('validate', () => {
         type: 'number'
       }
     })).rejects.toMatchInlineSnapshot(`
-      [Error: Invalid resume:
-        data must be number]
+      [Error: Invalid resume: 1 problem found
+
+        ✖ data must be number
+          at:    (root)
+          rule:  type (expected number)
+          found: "thomas" (string)
+          hint:  the resume must be of type number.]
     `);
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resume-cli",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "The JSON Resume command line interface",
   "main": "build/main.js",
   "engines": {