版本守护

对任何项目的严格版本治理——SemVer和CalVer执行,语言-不可知的显示支持,git hooks,更动日志验证,文件同步,以及重播版扫描.

VersionGuard 保存您的列表,更改日志条目, git 标记, 并配置版本引用同步, 因此人类和 LLM 代理停止传输混乱的发布状态 .

为什么它存在

不同地点的版本中断 :

• 版本在文档、 CI 配置和 Docker 文件之间获得硬码
• 更改日志条目被遗忘或使用错误的段落名称
• 标记从软件包版本漂移
• SemVer和CalVer的规则在压力下弯曲
• 代理人员使用快捷键, 将重播保留在无效的释放状态

版本Guard将那些变成可执行的检查,并有面向修复的反馈.

它会做什么

• 验证带有可配置规则的SemVer和CalVer格式
• 继续根据您的清单同步配置文件( package.json, Cargo.toml, pyproject.toml等)
• 扫描整个重播版本的文字( 默认启用)
• 对照您的软件包登记表( npm、 箱子. io、 PyPI等) 核实发布状态
• 保留带有区域执行的更改日志结构
• 安装合作基特钩 pre-commit, (中文(简体) ), pre-push,以及 post-tag
• 提供 CLI 命令进行校验、同步、出错和标记
• 需要钩子或工作树脏时拒绝不安全标记
• 用于人类和LLM代理的内置CKM帮助系统(vg ckm(中文(简体) )

它运行的地方

版本Guard在开发生命周期的三点执行:

1. 本地 dev( 挂钩) : pre-commit 财务报告和审定财务报表 pre-push 钩子运行 vg validate 自动。 此抓取版本漂移,更改日志问题,以及代码离开开发者的机器前同步不匹配. 这是主要执行点.

2. CI( GitHub 动作 ): vg validate 在CI中作为一个建筑门运行。 这捕捉到钩子漏掉的任何东西( 钩可以跳过) --no-verify),在每个PR上验证,并确保Depabot PRs不会打破版本一致性.

3. CLI(开发工作流程): vg check, (中文(简体) ), vg fix, (中文(简体) ), vg sync, (中文(简体) ), vg tag, (中文(简体) ), vg doctor ——开发者和代理在发行流程中使用的手动指令.

谁需要呢

• 任何船舶版本软件的项目 并想要停止版本相关的漂移 : 在 docs 中 stale 安装命令, 缺少更改日志条目, CI 配置或 Dockerfile 中硬码版本字符串, 标记/ 明显不匹配
• 使用AI代理的团队 修改代码的 VG 是代理机跳过版本步骤时抓取的护栏
• Polyglot项目 在npm、rust、Python、Dart、PHP、Java和更多

安装

npm install -D @codluv/versionguard@latest
vg init
vg hooks install

vg 是用于 versionguard两者工作相同.

这给你:

• (单位:千美元) .versionguard.yml 配置文件
• 管理着的钩子
• 围绕您的列表构建的本地版本政策

快开始

运行基本版本检查 :

vg check

运行完整的仓库验证( 包括扫描、 守护和默认公布检查) :

vg validate

对于CI或代理工作流程:

vg validate --json

将配置的文件同步到显示的版本 :

vg sync

自动修复常见问题 :

vg fix

示例输出

有效版本 :

Current version: 1.2.3
Versioning type: semver

✓ Version is valid

有可操作指导的无效版本 :

Current version: v1.0.0
Versioning type: semver

✗ Version has issues:

  ✗ Version should not start with 'v': v1.0.0

How to fix:
  → Remove the 'v' prefix
    Run: npm version 1.0.0

配置

版本Guard使用单一的YAML配置文件. 两者 semver: 财务报告和审定财务报表 calver: 块总是存在的——变化 type 切换.

示例

versioning:
  type: semver
  semver:
    allowVPrefix: false
    allowBuildMetadata: true
    requirePrerelease: false
  calver:
    format: "YYYY.MM.PATCH"
    preventFutureDates: true

sync:
  files:
    - "README.md"
    - "CHANGELOG.md"
  patterns:
    - regex: '(version\s*[=:]\s*["'])(.+?)(["'])'
      template: '$1{{version}}$3'
    - regex: '(##\s*\[)(.+?)(\])'
      template: '$1{{version}}$3'

changelog:
  enabled: true
  file: "CHANGELOG.md"
  strict: true
  requireEntry: true
  enforceStructure: false
  sections:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security

# All checks below are enabled by default — opt OUT via config
guard:
  enabled: true          # hook bypass detection

publish:
  enabled: true          # registry publish status verification
  timeout: 5000          # ms, fail-open on timeout

scan:
  enabled: true          # repo-wide stale version detection
  allowlist: []

git:
  hooks:
    pre-commit: true
    pre-push: true
    post-tag: true
  enforceHooks: true

ignore:
  - "node_modules/**"
  - "dist/**"
  - ".git/**"
  - "*.lock"

支持的版本模式

交换器

版本Guard 支持严格的语义性版本验证,并通过 semver: 块 :

• MAJOR.MINOR.PATCH 提前释放(1.2.3-alpha.1)和建立元数据(1.2.3+build.5(中文(简体) )
• allowVPrefix ——宽容 v1.2.3 格式( 在解析前划出)
• allowBuildMetadata - 允许或拒绝 +build 元数据后缀
• requirePrerelease · 要求在每个版本上预发标签
• schemeRules.allowedModifiers ——白名单预释标签(如:, alpha, (中文(简体) ), beta, (中文(简体) ), rc(中文(简体) )
• 优先比较和递增帮助

卡尔维尔

支持所有 calver.org 令牌的可编译以符号为基础的格式字符串 :

• 年份 : YYYY, (中文(简体) ), YY, (中文(简体) ), 0Y
• 月数 : MM, (中文(简体) ), M, (中文(简体) ), 0M
• 周数 : WW, (中文(简体) ), 0W
• 天数 : DD, (中文(简体) ), D, (中文(简体) ), 0D
• 计数器 : MICRO, (中文(简体) ), PATCH

CalVer验证可以拒绝未来日期的版本并强制修改允许列表.

语言不可知表

版本Guard从任何支持的列表中读取版本:

• package.json (节点.js), Cargo.toml (鲁斯特), pyproject.toml (P
• pubspec.yaml (达特/弗卢特), composer.json (菲律宾), pom.xml (贾瓦/马文)
• VERSION (平面文本), Git 标记( Go/ Swift), 自定义正则图案

设定 manifest.source: auto 用于自动检测.

图标

Git 钩子行为

版本Guard可以安装这些钩:

• pre-commit
• pre-push
• post-tag

何时 git.enforceHooks 被启用,释放标记也期望有管理下的钩子.

医生指挥

使用 doctor 在发布前需要单行录准备报告时:

vg doctor

对于CI或代理工作流程:

vg doctor --json

它报告说:

• 当前软件包版本
• 版本有效性
• 同步状态
• 换行准备
• 钩子安装状态
• 工作树木清洁

验证 JSON 输出

使用 validate --json 当您需要机器可读验证输出时:

vg validate --json

JSON有效载荷包括:

• valid
• version
• versionValid
• syncValid
• changelogValid
• scanValid
• guardValid
• publishValid
• publishCheck
• guardReport
• errors
• hook
• postTag

纠缠行为

versionguard tag 故意严格.

在下列情况下,法院可拒绝继续审理:

• 需要挂钩,但没有安装
• 工作树是肮脏的
• 请求的标签已经存在
• 软件包版本或更改日志状态无效
• 同步文件已过期

这使得释放标记不会成为绕行正常验证的绕道.

稳定政策

1.x保持所有CLI命令和配置格式的后向相容性. 断裂变化只发生于2.0+.

贬值的旗帜--strict, (中文(简体) ), --scan继续使用1.x并打印出警告。 他们的行为现在是默认的。 要选择退出特定检查, 请使用配置 :

guard:
  enabled: false
scan:
  enabled: false
publish:
  enabled: false

典型工作流程

实施前验证

vg validate

修改手动版本后修复漂移

npm version patch
vg fix

建议并应用下一个版本

vg bump --apply

安全创建释放标签

vg tag 1.2.3 -m "Release 1.2.3"

使用更改器

版本担保和 更改 是处理释放生命周期不同部分的补充工具.

更改器决定下一个版本 。 版本Guard验证结果正确.

建议的工作流程

# 1. Add a changeset when making changes
npx changeset

# 2. When ready to release, version the packages
npx changeset version

# 3. VersionGuard validates the new state
vg validate

# 4. Publish
npx changeset publish

CI 整合

在"GitHub Action"中,两个工具都按顺序运行. 更改器在等待更改器时创建"Version套件"PR. 版本Guard在发布前验证结果:

- run: npm run build
- run: vg validate
- uses: changesets/action@v1
  with:
    publish: npx changeset publish --access public

版本Guard不替换更改器,也不与之相冲突. 使用变换器进行发布自动化. 使用版本Guard来发布正确性.

发展

本储存库使用现代无害环境管理工具链:

• 用于构建的虚拟
• 测试测试
• 用于格式化和基线衬线化的生物群落
• 语义类型语言的 ESLintScript linting

有用命令 :

npm run lint
npm test
npm run build

Forge 命令 :

npm run forge:check
npm run forge:test
npm run forge:build
npm run forge:doctor

初始化或刷新 Forge 脚手架 :

npm run forge:docs:init

运行单个测试文件 :

npx vitest run src/__tests__/semver.test.ts

按名称进行单一测试 :

npx vitest run src/__tests__/calver.test.ts -t "increments patch-based versions"

文档

• 产品视觉: docs/VISION.md
• 经核实的功能分类账和路线图: docs/FEATURES.md
• CKM模块文档: src/ckm/README-CKM.md
• 捐助方代理指导: AGENTS.md

福尔吉

这回波是用 @forge-ts/cli 和项目配置 forge-ts.config.ts。 。 。 .

有用命令 :

npm run forge:check
npm run forge:test
npm run forge:build
npm run forge:doctor

目前情况:

• 安装并初始化
• forge-ts check 目前报告大量TSDoc债务
• 生成的文献 文物被写入 docs/

建议的工作流程:

npm run forge:check
npm run forge:build

然后按照Forge报告的顺序解决TSDoc问题.

许可证

麻省理工学院