用途:manage-bans 用于创建和管理被禁止的 AST(抽象语法树)模式,阻止特定代码构造出现。当用户想禁用某代码模式或添加 tree-sitter lint 规则时使用。
规则来源:由 preToolUse 钩子检查两个来源。其一是全局文件 $HOME/.BANNED_AST.md,适用于所有编辑。其二是被编辑文件任意父目录中的 BANNED_AST.md,可包含多条规则,作用域覆盖该子树。当两处定义同名规则时,离被编辑文件更近的 BANNED_AST.md 优先。
规则格式:每个规则以 --- frontmatter 开始,含必填字段 name(小写、可用连字符的唯一标识)与 message(检测到该模式时显示的拒绝信息,应说明禁用原因并建议替代方案),随后是 --- 和 Tree Sitter 查询主体。同一文件可堆叠多条规则,各自用 frontmatter 分隔。查询使用 S-expression 语法,可带 #eq?、#match? 等谓词。
验证:编写规则后应使用 validate-rule.mts 脚本验证,以捕获查询语法错误并确认规则只匹配预期模式:node ban-ast/scripts/validate-rule.mts --lang ts --query '<tree-sitter-query>' --should-match '<should be flagged>' --should-not-match '<allowed>'。--lang 默认 ts,支持 ts、js、tsx、py、rs、go、c、cpp、cs、java、rb 等;--should-match 与 --should-not-match 可重复多次;不传这两个参数时只检查查询语法是否有效。测试失败时脚本以退出码 1 结束。
覆盖机制:若某被禁模式确有必要,可在新代码中加入理由注释绕过该规则:// <no-eval> justification: required for dynamic plugin loading。钩子会查找 <rule-name> justification: <非空理由>,理由必须非空。
限制:未提供收费、价格、平台支持范围等信息;具体使用依赖 vscode-team-kit 及其 ban-ast 脚本环境。