Skip to content
Big PlanBig Plan is in alpha

big-plan validate

Synopsis

Section titled “Synopsis”
big-plan validate <input.mdx>

Arguments

Section titled “Arguments”
Argument Required Behaviour
input.mdx Yes The plan to check, resolved against the current working directory

validate accepts no output argument and rejects a second positional argument.

What it does

Section titled “What it does”

validate reads and checks the plan without choosing an output path, creating a directory, or writing a file. It performs three checks:

  1. The shared static-subset MDX and component compiler accepts the authored structure.
  2. Big Plan renders the complete HTML document in memory, including React component presentation, Markdown transforms, shell composition, and serialization.
  3. The authored plan passes every registered linting rule.

Lint is intentionally stricter than structural compilation. render applies the same linting rules after derivation and before writing, so a plan that fails lint never becomes a review document; compile continues to accept legal Markdown that a quality rule flags. See Linting rules for every rule and its conservative matching boundaries. Rendering the document in memory does not replace visual review: browser layout, readability, and whether the page matches author intent still require a human.

Result

Section titled “Result”
  • validated: the absolute input path.
  • title: the document title.
  • sections and components: the validated counts.
  • help: a reminder that lint checks only what is statically analyzable, so the rendered document still needs rereading against the guidance principles.

It writes no output.

Errors

Section titled “Errors”
Code Raised when Exit
GUIDANCE_REQUIRED A current guidance acknowledgment cannot be verified for this working directory and a state directory is writable 2
VALIDATION_ERROR The input argument is missing, a second positional argument is present, an option is unknown, the MDX is invalid, or the plan fails authoring lint 2
INPUT_NOT_FOUND The input cannot be read; the message carries the resolved absolute path 1

If no state directory is writable, validate continues with a warning that guidance acknowledgment could not be verified. Run big-plan guidance and follow its principles, or set BIG_PLAN_STATE_DIR to a writable directory to restore the gate.

Troubleshooting

Section titled “Troubleshooting”
  • Only one diagnostic came back. An MDX syntax error can stop parsing before component validation begins. Fix it and run again to see the rest.
  • It passed and the plan still reads badly. Validation answers whether Big Plan can render the plan and whether it passes every statically analyzable rule. It answers nothing about whether the plan reads well.
  • A rule fired on something you believe is correct. Every rule documents what it deliberately leaves alone; check Lint rules.
Section titled “Related”