feat: syntax version validation, upgrade command, and unknown block detection#146
Merged
feat: syntax version validation, upgrade command, and unknown block detection#146
Conversation
Prevent future release-please breakage by adding a restriction against manually editing CHANGELOG.md, which is managed by release-please.
Address review findings: - PS004 → PS018 (PS004 already taken by required-guards) - Clarify cumulative block lists in registry - Scope regex replace to @meta block only - Add CLI registration details and file manifest - Define preset severities and edge cases for custom blocks - Use existing compareVersions from core - Remove directives from interface (YAGNI)
- Add isValidSemver guard in PS018 to prevent compareVersions throw - Specify meta block boundary finding for --fix implementation - Use rule names (not IDs) as preset keys per convention - PS019 uses walkBlocks + isBlockType from existing utilities - Move Levenshtein to core/utils for reuse - Add explicit no-downgrade rule for --fix - Add documentation update plan - Expand files modified with grouped sections
9 tasks across 7 chunks: Levenshtein utility, syntax registry, PS018/PS019 rules, validate --fix, prs upgrade, verification, docs. Reviewed and fixed: type discriminators, ExtendBlock.targetPath, Block|ExtendBlock narrowing, readdir instead of glob, merged imports.
Introduces SYNTAX_VERSIONS registry mapping 1.0.0 and 1.1.0 to their supported block types, plus helper functions getLatestSyntaxVersion, isKnownSyntaxVersion, getBlocksForVersion, and getMinimumVersionForBlock.
- Validates that .prs files declare a known syntax version - Warns when blocks are used that require a higher syntax version - Checks both @blocks and @extends blocks via walkBlocks - Skips unknown block names (deferred to PS019) - Skips invalid semver, non-string syntax, and missing meta - Registered in allRules after PS017 (skillContracts) - Added to all 3 security presets: warning/warning/off
…-fix Add --fix option to `prs validate` that auto-fixes syntax version declarations in .prs files. When a file uses blocks requiring a higher syntax version than declared, --fix updates the @meta syntax field. Exports fixSyntaxVersion and discoverPrsFiles helpers for reuse by the upcoming upgrade command.
- core: add utils/levenshtein and syntax-versions to modules table; add API reference section documenting SYNTAX_VERSIONS, SyntaxVersionDef, LATEST_SYNTAX_VERSION, getLatestSyntaxVersion, isKnownSyntaxVersion, getBlocksForVersion, getMinimumVersionForBlock, levenshteinDistance, and findClosestMatch - validator: add full validation rules table (PS001-PS019) including new PS018 syntax-version-compat and PS019 unknown-block-name - cli: document prs validate --fix and prs upgrade [--dry-run] in both the commands table and the detailed command usage section
- Fix brace scanner to respect string literals in fixSyntaxVersion - Extract duplicated getBlockName helper to walker.ts - Add syntax version docs to language reference and SKILL.md
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Bundle ReportChanges will increase total bundle size by 14.07kB (1.35%) ⬆️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: promptscript-cliAssets Changed:
|
prs init was writing syntax: "1.4.7" (package version) instead of syntax: "1.1.0" (latest syntax version). This caused PS018 to warn on freshly initialized projects.
Snapshot directories were renamed when language.md gained the syntax versions section (line numbers shifted), but the claude.md files were not regenerated at the new paths.
- Add discoverPrsFiles tests: find files, subdirectories, non-existent dir, no .prs files - Add upgradeCommand integration tests using temp directories: upgrade, skip-at-latest, dry-run, skip-no-meta, empty dir - Update doc snapshots
Cover runFix function through validateCommand({ fix: true }):
- Fix syntax when blocks require higher version
- No fixes needed when syntax is correct
- Handle empty .promptscript directory
- Skip files without syntax field
- Reject --fix with --format json
…flows/@prompts Documentation incorrectly listed @skills as a 1.1.0 addition and omitted @workflows and @prompts. Fixed to match the code registry: - 1.0.0: includes @skills along with other core blocks - 1.1.0: adds @agentS, @workflows, @prompts
**/CLAUDE.md in .gitignore matches lowercase claude.md on macOS (case-insensitive FS), preventing doc snapshot files from being committed. Added negation rule for docs/__snapshots__/**/claude.md.
This was referenced Mar 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@promptscript/coremapping versions to supported blocks (1.0.0→ 11 blocks,1.1.0→ +agents, workflows, prompts)syntax-version-compat— warns when declared syntax version is unknown or blocks require a higher version than declaredunknown-block-name— warns on unknown block types with Levenshtein fuzzy matching (e.g.,@agenst→ "Did you mean @agentS?")prs validate --fix— auto-fixes syntax version to minimum required (conservative)prs upgrade [--dry-run]— bumps all files to latest syntax version (aggressive)Motivation
Users could write
syntax: "1.4.7"(confusing package version with syntax version) orsyntax: "1.0.0"with@agents(a 1.1.0 feature) — both compiled silently. Typos like@agenstalso went undetected.Test plan
fixSyntaxVersion(upgrade, no-downgrade, meta-scoped, string literals)