checking-and-formatting.md

Checking and formatting

Usage guide

Check content

cac check cv.md
cac check cv.md --explain
cac check cv.md --strict
cac check cv.yaml

--explain prints the normalized CV as JSON before content diagnostics, showing how headings and fields were interpreted. Rich text appears as canonical Markdown inside JSON strings.

Ordinary content suggestions do not stop cac build. --strict makes any reported diagnostic fail the check, which is useful when enforcing editorial rules. Invalid syntax, conflicting fields, and invalid dates must be corrected. The check command defaults to cv.md; specify the filename for other sources.

Format source files

cac fmt
cac fmt cv.md
cac fmt cv.json
cac fmt cv.yaml --dry-run
cac fmt cv.toml
cat cv.json | cac fmt - --input-format json

With no filename, cac fmt uses settings.json's root, falling back to cv.md. The filename extension selects the format; --input-format overrides it. Standard input defaults to Markdown. JSON Resume can use --input-format jsonresume.

The default replaces the source file after verifying that parsing preserves its CV data. Invalid input or a failed preservation check leaves the file unchanged.

Command	Output	Writes the file?	Exit status
cac fmt cv.md	FORMATTED cv.md	Yes	Zero on success
cac fmt cv.md --dry-run (already formatted)	PASS	No	Zero
cac fmt cv.md --dry-run (needs formatting)	Error explaining that formatting is needed	No	Nonzero
cac fmt -	Formatted source on stdout	No	Zero on success

--dry-run reports status, not a diff or a formatted preview. Parse errors also exit nonzero. With stdin, --dry-run checks the supplied text instead of printing formatted source. Without --dry-run, stdin produces formatted stdout because there is no source file to replace.

Check formatting without writing

cac fmt --dry-run

Use this in automated checks to fail when the configured project source needs formatting. To apply the changes locally, run cac fmt, then repeat the dry run. This checks source formatting; cac check separately checks CV content.

Migrating older commands

Replace cac fmt FILE --check with cac fmt FILE --dry-run. Replace cac fmt FILE --write with cac fmt FILE; both old options have been removed. Previously, plain cac fmt FILE printed the formatted source. It now writes the file. To inspect formatted output without writing, use stdin:

cat cv.md | cac fmt -
cat cv.json | cac fmt - --input-format json

Formatting preserves the source format. Bare Markdown stays bare Markdown; FieldMark keeps its existing fields. Markdown formatting tidies trailing whitespace and final blank lines while retaining hard breaks, comments, metadata boundaries, headings, links, and date notation. It does not insert Kind: fields or directives. JSON is pretty-printed; YAML and TOML are serialized in their own syntax, retaining supplied fields rather than adding normalized CV defaults. YAML/TOML comments and original quoting may not survive serialization.

Use conversion when you want another representation. Formatting never rewrites achievements or invents facts.

Editor snippets

Copy cac.code-snippets into your project's .vscode/ directory, or add its entries to your editor's user snippets. In VS Code Markdown files, use cac-profile, cac-section, cac-experience, or cac-project to insert a template. Fill the placeholders and remove optional fields you do not need.