A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!
TypeScript agent-skillsaidsh-pluginhacktoberfestjavascriptmcp-serverreactresume-builderself-hostedtypescript
import type { IconName } from "@/ui";
import type { PageMapTarget } from "@reactive-resume/pdf/page-map";
import type { AtsCategory, AtsFinding, AtsReport } from "@reactive-resume/resume/ats";
import type { ResumeData } from "@reactive-resume/schema/resume/data";
import { i18n } from "@lingui/core";
import { ph, t } from "@lingui/core/macro";
import { getResumeSectionTitle } from "@reactive-resume/pdf/section-title";
import { atsRuleCategory, mergeIntoPreviousEntry } from "@reactive-resume/resume/ats";
/** How a card fixes its issue: in one step on the resume (with undo), or by opening the entry in Write. */
type IssueFix =
| { kind: "apply"; label: string; icon: IconName; done: string; apply: (draft: ResumeData) => void }
| { kind: "write"; label: string; target: PageMapTarget };
export type CheckIssue = {
key: string;
/** 1-based, in the order the cards list them; the pin on the page carries the same number. */
number: number;
finding: AtsFinding;
category: AtsCategory;
title: string;
body: string;
fix: IssueFix;
/** "Keep" instead of "Ignore": the issue follows from a design choice that is the author's to make. */
keepLabel: boolean;
/** The block on the page the issue is about, for its pin; null for page-wide settings. */
target: PageMapTarget | null;
};
export const getCategoryName = (category: AtsCategory) =>
({
contact: t`Contact details`,
dates: t`Dates`,
layout: t`Layout`,
headings: t`Section headings`,
writing: t`Writing`,
})[category];
export const getCategoryDescription = (category: AtsCategory) =>
({
contact: t`Name, email, phone and location are found, and links are full addresses.`,
dates: t`Every entry has dates in a form systems read, in order, and none in the future.`,
layout: t`Text comes out in the order a person reads it, at a size and spacing that survive.`,
headings: t`Sections use headings systems recognize, and work experience shows.`,
writing: t`Every role says what you did. Opinions on wording live in the Writing tab.`,
})[category];
const decodeToken = (token: string) => token.replace(/~1/g, "/").replace(/~0/g, "~");
const tokensOf = (pointer: string) => pointer.split("/").slice(1).map(decodeToken);
/** The section a pointer is in: the summary, a built-in section's key or a custom section's id. */
function sectionIdOf(tokens: readonly string[], data: ResumeData): string | undefined {
const [head, next] = tokens;
if (head === "summary") return "summary";
if (head === "sections") return next;
if (head === "customSections") return data.customSections[Number(next)]?.id;
return undefined;
}
function itemIdOf(tokens: readonly string[], data: ResumeData): string | undefined {
const itemsIndex = tokens.indexOf("items");
if (itemsIndex === -1) return undefined;
let node: unknown = data;
for (const token of tokens.slice(0, itemsIndex + 2)) node = (node as Record<string, unknown> | undefined)?.[token];
const id = (node as { id?: unknown } | undefined)?.id;
return typeof id === "string" ? id : undefined;
}
/** The block a finding is about: the header for contact details, else its section or entry. */
function getFindingTarget(finding: AtsFinding, data: ResumeData): PageMapTarget | null {
const tokens = tokensOf(finding.pointer);
if (tokens[0] === "basics" || tokens[0] === "picture") return { kind: "header" };
const sectionId = sectionIdOf(tokens, data);
if (!sectionId) return null;
const itemId = itemIdOf(tokens, data);
return itemId ? { kind: "item", sectionId, itemId } : { kind: "section", sectionId };
}
/** The printed name of a section: the title the author gave it, else its type's name. */
export const getSectionName = getResumeSectionTitle;
function getEntryName(data: ResumeData, target: PageMapTarget | null): string {
if (target?.kind !== "item") return t`This entry`;
const section =
data.sections[target.sectionId as keyof typeof data.sections] ??
data.customSections.find((entry) => entry.id === target.sectionId);
const entry = section?.items.find((entry) => entry.id === target.itemId);
// coordinator: replace entry/field labels with M3-T5 fields.ts after merge; ids remain navigation seam.
const title =
entry &&
("company" in entry ? entry.company : "school" in entry ? entry.school : "name" in entry ? entry.name : "");
return title ? `“${title}”` : t`This entry`;
}
/** Sets the value a finding's pointer names (the pointer still has array indexes, which match `draft`). */
function setAt(draft: ResumeData, pointer: string, value: unknown) {
const tokens = tokensOf(pointer);
const last = tokens.pop();
let node: unknown = draft;
for (const token of tokens) node = (node as Record<string, unknown> | undefined)?.[token];
if (node && last !== undefined) (node as Record<string, unknown>)[last] = value;
}
const HAS_SCHEME = /^[a-z][a-z\d+.-]*:/i;
type Message = { title: string; body: string; fix: IssueFix; keepLabel?: boolean };
function describeFinding(finding: AtsFinding, data: ResumeData, target: PageMapTarget | null): Message {
const value = String(finding.params?.value ?? "");
const section = String(finding.params?.section ?? "");
const minimum = Number(finding.params?.minimum ?? 0);
const write = (label: string): IssueFix => ({ kind: "write", label, target: target ?? { kind: "header" } });
const entry = getEntryName(data, target);
switch (finding.code) {
case "MISSING_NAME":
return {
title: t`Your name is missing`,
body: t`Systems file you under the name at the top of the page.`,
fix: write(t`Add your name`),
};
case "MISSING_EMAIL":
return {
title: t`No email address`,
body: t`Most systems file candidates by email address.`,
fix: write(t`Add an email`),
};
case "MALFORMED_EMAIL":
return {
title: t`Email address won't be recognized`,
body: t`“${value}” isn't a plain address like [email protected].`,
fix: write(t`Edit the email`),
};
case "MISSING_PHONE":
return {
title: t`No phone number`,
body: t`Some application systems ask for one before you can apply.`,
fix: write(t`Add a phone number`),
};
case "MISSING_LOCATION":
return {
title: t`No location`,
body: t`A city and country let roles be matched to where you are.`,
fix: write(t`Add a location`),
};
case "MALFORMED_URL": {
const url = `https://${value}`;
return {
title: t`A link isn't a full address`,
body: t`Some systems only recognize links that start with https://. This one reads as plain text: “${value}”.`,
fix: HAS_SCHEME.test(value)
? write(t`Edit the link`)
: {
kind: "apply",
label: t`Use ${url}`,
icon: "link-simple-horizontal",
done: t`Link updated`,
apply: (draft) => setAt(draft, finding.pointer, url),
},
};
}
case "PICTURE_PRESENT":
return {
title: t`Your resume has a photo`,
body: t`Some systems mishandle images, and photos are discouraged in some countries.`,
fix: {
kind: "apply",
label: t`Hide the photo`,
icon: "eye-slash",
done: t`Photo hidden`,
apply: (draft) => {
draft.picture.hidden = true;
},
},
};
case "EMPTY_PERIOD":
return {
title: t`An entry has no dates`,
body: t`${entry} doesn't say when. Dates place it on your timeline.`,
fix: write(t`Add dates`),
};
case "UNPARSEABLE_PERIOD":
return {
title: t`Dates won't be read`,
body: t`“${value}” isn't a form systems recognize, such as Mar 2020 – Present.`,
fix: write(t`Fix the dates`),
};
case "UNPARSEABLE_DATE":
return {
title: t`A date won't be read`,
body: t`“${value}” isn't a form systems recognize, such as March 2022.`,
fix: write(t`Fix the date`),
};
case "REVERSED_PERIOD":
return {
title: t`Dates run backwards`,
body: t`“${value}” ends before it starts.`,
fix: write(t`Fix the dates`),
};
case "FUTURE_DATED_PERIOD":
return {
title: t`Dates start in the future`,
body: t`“${value}” starts after today. Check the year, or mark it as current.`,
fix: write(t`Fix the dates`),
};
case "SECTION_MISSING_FROM_LAYOUT": {
const name = getSectionName(data, section);
return {
title: t`${name} never prints`,
body: t`It has entries but isn't placed on a page.`,
fix: {
kind: "apply",
label: t`Add it to page 1`,
icon: "plus",
done: t`${name} added to page 1`,
apply: (draft) => {
const [page] = draft.metadata.layout.pages;
if (page) page.main.push(section);
else draft.metadata.layout.pages.push({ fullWidth: false, main: [section], sidebar: [] });
},
},
};
}
case "NO_VISIBLE_EXPERIENCE":
return {
title: t`No work experience shows`,
body: t`Systems look for an experience section. Projects or volunteering can show the same history.`,
fix: { kind: "write", label: t`Add experience`, target: { kind: "section", sectionId: "experience" } },
};
case "FRAGMENTED_ENTRY":
return {
title: t`Looks like part of the entry above`,
body: t`${entry} has no dates and reads like a sentence cut off the entry above it, which happens when a PDF import splits a bullet. Adding dates would make it look like a separate job.`,
fix: {
kind: "apply",
label: t`Merge into previous entry`,
icon: "arrow-up",
done: t`Merged into the entry above`,
apply: (draft) => {
mergeIntoPreviousEntry(draft, finding.pointer);
},
},
};
case "MISSING_EXPERIENCE_DESCRIPTION":
return {
title: t`A role has no description`,
body: t`${entry} names the role but not what you did, so it adds no keywords.`,
fix: write(t`Describe the role`),
};
case "NON_STANDARD_SECTION_TITLE": {
const title = String(finding.params?.title ?? "");
return {
title: t`“${title}” isn't a heading systems look for`,
body: t`They look for headings such as Experience, Education and Skills.`,
fix: {
kind: "apply",
label: t`Use the standard heading`,
icon: "text-t",
done: t`Heading changed`,
// An empty title prints the section type's name in the resume's language.
apply: (draft) => setAt(draft, finding.pointer, ""),
},
};
}
case "MULTI_COLUMN_PROSE_SECTION": {
const name = getSectionName(data, section);
const columns = Number(finding.params?.columns ?? 2);
return {
title: t`${name} is split into ${ph({ columns: i18n.number(columns) })} columns`,
body: t`Columns can scramble the order text is read in.`,
fix: {
kind: "apply",
label: t`Use one column`,
icon: "list-dashes",
done: t`${name} uses one column`,
apply: (draft) => setAt(draft, finding.pointer, 1),
},
};
}
case "PROSE_SECTION_IN_SIDEBAR": {
const name = getSectionName(data, section);
return {
title: t`${name} sits in the sidebar`,
body: t`Sidebars are often read last, or mixed into the main column.`,
fix: {
kind: "apply",
label: t`Move it to the main column`,
icon: "arrow-right",
done: t`${name} moved to the main column`,
apply: (draft) => {
for (const page of draft.metadata.layout.pages) {
if (!page.sidebar.includes(section)) continue;
page.sidebar = page.sidebar.filter((id) => id !== section);
page.main.push(section);
}
},
},
};
}
case "TWO_COLUMN_LAYOUT": {
const names = String(finding.params?.sections ?? "")
.split(",")
.filter(Boolean)
.map((id) => getSectionName(data, id))
.join(", ");
return {
title: t`Sidebar is read after the main column`,
body: t`${names} come last in the text. Most systems still find them; some don't.`,
keepLabel: true,
fix: {
kind: "apply",
label: t`Switch to one column`,
icon: "list-dashes",
done: t`Switched to one column`,
// Full-width pages print no sidebar, so its sections move into the main column first.
apply: (draft) => {
for (const page of draft.metadata.layout.pages) {
if (page.fullWidth || page.sidebar.length === 0) continue;
page.main.push(...page.sidebar);
page.sidebar = [];
page.fullWidth = true;
}
},
},
};
}
case "SMALL_BODY_FONT":
return {
title: t`Body text is very small`,
body: t`Text under ${ph({ minimum: i18n.number(minimum) })} pt can be misread when a system re-renders it.`,
fix: {
kind: "apply",
label: t`Use ${ph({ minimum: i18n.number(minimum) })} pt`,
icon: "text-aa",
done: t`Body text set to ${ph({ minimum: i18n.number(minimum) })} pt`,
apply: (draft) => setAt(draft, finding.pointer, minimum),
},
};
case "TIGHT_LINE_HEIGHT":
return {
title: t`Lines are packed tightly`,
body: t`Lines this close can run together when read. Use at least ${ph({ minimum: i18n.number(minimum) })}.`,
fix: {
kind: "apply",
label: t`Use ${ph({ minimum: i18n.number(minimum) })}`,
icon: "sliders-horizontal",
done: t`Line height set to ${ph({ minimum: i18n.number(minimum) })}`,
apply: (draft) => setAt(draft, finding.pointer, minimum),
},
};
case "TIGHT_PAGE_MARGINS":
return {
title: t`Margins are very narrow`,
body: t`Text this close to the edge can be cut off. Use at least ${ph({ minimum: i18n.number(minimum) })} pt.`,
fix: {
kind: "apply",
label: t`Use ${ph({ minimum: i18n.number(minimum) })} pt margins`,
icon: "sliders-horizontal",
done: t`Margins set to ${ph({ minimum: i18n.number(minimum) })} pt`,
apply: (draft) => setAt(draft, finding.pointer, minimum),
},
};
}
}
/** The open findings as numbered cards, in the report's order (most severe first). */
export function buildIssues(report: AtsReport, data: ResumeData): CheckIssue[] {
return report.findings.map((finding, index) => {
const target = getFindingTarget(finding, data);
const message = describeFinding(finding, data, target);
return {
key: finding.key,
number: index + 1,
finding,
category: atsRuleCategory(finding.code),
title: message.title,
body: message.body,
fix: message.fix,
keepLabel: message.keepLabel ?? false,
target,
};
});
}