@abco20/btxml-checker 0.1.0

package/dist/rules.d.ts

@@ -0,0 +1,356 @@
+import { f as ConfigSeverity, E as EffectiveFileConfig, a as RawBtxmlConfig, C as ConfigDiagnostic } from './types-BgqDzlJ8.js';
+import { z } from 'zod';
+import { d as createDiagnostic, e as DiagnosticSeverity } from './diagnostic-B5htzyJ9.js';
+import { a as NodeUsagePolicy } from './types-SY4-jKCn.js';
+import './ast-BbfR3S_b.js';
+import './public-types-B2noBQY9.js';
+import './types-BaOc_AYN.js';
+
+type RuleOptionDoc = {
+    name: string;
+    type: string;
+    default?: string;
+    description: string;
+};
+type RuleRegistryEntry<TOptions = unknown> = {
+    code: string;
+    codes?: readonly string[];
+    defaultSeverity: ConfigSeverity;
+    optionsSchema?: z.ZodType<TOptions>;
+    options?: RuleOptionDoc[];
+    description: string;
+};
+declare const RULES: {
+    readonly "script/valid-syntax": {
+        readonly code: "BT401_INVALID_SCRIPT_SYNTAX";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Script-bearing attributes must parse as valid BT.CPP scripts.";
+    };
+    readonly "script/no-unknown-variable": {
+        readonly code: "BT404_UNKNOWN_SCRIPT_VARIABLE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Script-bearing attributes should not reference unknown variables.";
+    };
+    readonly "script/valid-assignment": {
+        readonly code: "BT405_ASSIGNMENT_TO_UNKNOWN_VARIABLE";
+        readonly codes: readonly ["BT405_ASSIGNMENT_TO_UNKNOWN_VARIABLE", "BT406_INVALID_COMPOUND_ASSIGNMENT", "BT410_SCRIPT_VARIABLE_TYPE_MISMATCH"];
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Script assignments must target known variables and use compatible types.";
+    };
+    readonly "script/valid-expression-type": {
+        readonly code: "BT407_INVALID_SCRIPT_OPERAND_TYPE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Script expressions must use operators with compatible operand types.";
+    };
+    readonly "script/valid-result-type": {
+        readonly code: "BT408_SCRIPT_RESULT_NOT_BOOL_COMPATIBLE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Condition-style script attributes must have a bool-compatible inferred result.";
+    };
+    readonly "xml/valid-root": {
+        readonly code: "BT001_INVALID_ROOT_ELEMENT";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Root element must be <root>.";
+    };
+    readonly "xml/require-btcpp-format": {
+        readonly code: "BT002_MISSING_BTCPP_FORMAT";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Root element must declare BTCPP_format=\"4\".";
+    };
+    readonly "tree/require-id": {
+        readonly code: "BT003_MISSING_BEHAVIOR_TREE_ID";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "BehaviorTree elements require an ID attribute.";
+    };
+    readonly "tree/no-duplicate-id-in-file": {
+        readonly code: "BT004_DUPLICATE_BEHAVIOR_TREE_ID";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "BehaviorTree IDs must be unique within a file.";
+    };
+    readonly "tree/no-duplicate-id": {
+        readonly code: "BT013_DUPLICATE_BEHAVIOR_TREE_ID_IN_WORKSPACE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "BehaviorTree IDs must be unique across the workspace.";
+    };
+    readonly "tree/no-unknown-subtree": {
+        readonly code: "BT005_UNKNOWN_SUBTREE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "A SubTree must resolve to a BehaviorTree or a configured model.";
+    };
+    readonly "tree/no-unknown-main-tree": {
+        readonly code: "BT010_UNKNOWN_MAIN_TREE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "main_tree_to_execute must reference a known BehaviorTree.";
+    };
+    readonly "tree/no-ambiguous-subtree": {
+        readonly code: "BT011_AMBIGUOUS_SUBTREE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "SubTree references must resolve to a single definition.";
+    };
+    readonly "tree/no-duplicate-node-model-id": {
+        readonly code: "BT006_DUPLICATE_NODE_MODEL_ID";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "TreeNodesModel elements must have unique IDs within the same model block.";
+    };
+    readonly "xml/no-unknown-top-level-element": {
+        readonly code: "BT009_UNKNOWN_TOP_LEVEL_ELEMENT";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Top-level elements must be BehaviorTree, TreeNodesModel, or configured include elements.";
+    };
+    readonly "include/require-path": {
+        readonly code: "BT301_MISSING_INCLUDE_PATH";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "include elements require a path attribute.";
+    };
+    readonly "include/no-missing-file": {
+        readonly code: "BT302_INCLUDE_NOT_FOUND";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Referenced include file does not exist.";
+    };
+    readonly "include/no-cycle": {
+        readonly code: "BT303_INCLUDE_CYCLE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Include graph cycles are not allowed.";
+    };
+    readonly "include/no-outside-root": {
+        readonly code: "BT306_INCLUDE_OUTSIDE_WORKSPACE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Includes must stay within the workspace root.";
+    };
+    readonly "include/no-unresolved-variable": {
+        readonly code: "BT304_UNRESOLVED_INCLUDE_PATH_VARIABLE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Include path variables must resolve before lookup.";
+    };
+    readonly "include/no-depth-exceeded": {
+        readonly code: "BT309_INCLUDE_DEPTH_EXCEEDED";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Include resolution must stay within the configured maximum depth.";
+    };
+    readonly "include/no-too-many-files": {
+        readonly code: "BT310_TOO_MANY_RESOLVED_FILES";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Include resolution must stay within the configured file limit.";
+    };
+    readonly "include/require-ros-package-resolver": {
+        readonly code: "BT312_ROS_PACKAGE_RESOLVER_MISSING";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "When include uses ros_pkg, a host resolvePackageUri capability must be provided.";
+    };
+    readonly "include/no-missing-ros-package": {
+        readonly code: "BT313_ROS_PACKAGE_NOT_FOUND";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "ros_pkg include must resolve to an existing ROS package root URI.";
+    };
+    readonly "include/report-external-used": {
+        readonly code: "BT307_EXTERNAL_INCLUDE_USED";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Reports when an allowed include resolves outside the workspace root.";
+    };
+    readonly "model/no-unknown-node": {
+        readonly code: "BT105_UNKNOWN_NODE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Node usages must resolve to a known model.";
+    };
+    readonly "model/require-port": {
+        readonly code: "BT101_MISSING_REQUIRED_PORT";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Required ports must be supplied.";
+    };
+    readonly "model/require-port-name": {
+        readonly code: "BT007_MISSING_PORT_NAME";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Port elements require a name attribute.";
+    };
+    readonly "model/no-duplicate-port-name": {
+        readonly code: "BT008_DUPLICATE_PORT_NAME";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Ports with the same name are not allowed.";
+    };
+    readonly "model/valid-port-name": {
+        readonly code: "BT116_INVALID_PORT_NAME";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Port names must be valid XML attribute names for BT nodes.";
+    };
+    readonly "model/no-unknown-port": {
+        readonly code: "BT102_UNKNOWN_PORT";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly optionsSchema: z.ZodObject<{
+            subTreePorts: z.ZodOptional<z.ZodEnum<{
+                strict: "strict";
+                loose: "loose";
+            }>>;
+        }, z.core.$strict>;
+        readonly options: [{
+            readonly name: "subTreePorts";
+            readonly type: "\"loose\" | \"strict\"";
+            readonly default: "loose";
+            readonly description: "Controls whether SubTree remap attributes are checked strictly.";
+        }];
+        readonly description: "Reports ports that are not declared by the resolved node model.";
+    };
+    readonly "model/valid-port-value": {
+        readonly code: "BT103_INVALID_PORT_VALUE_TYPE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Port values must match the declared type.";
+    };
+    readonly "model/no-blackboard-type-mismatch": {
+        readonly code: "BT111_BLACKBOARD_TYPE_MISMATCH";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly optionsSchema: z.ZodObject<{
+            allowStringEntryCompatibility: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        readonly options: [{
+            readonly name: "allowStringEntryCompatibility";
+            readonly type: "boolean";
+            readonly default: "true";
+            readonly description: "Treat std::string blackboard entries as runtime-compatible with other port types, matching BT.CPP's existing-entry special case.";
+        }];
+        readonly description: "Blackboard entries must not mix incompatible resolved port types.";
+    };
+    readonly "model/valid-port-default-value": {
+        readonly code: "BT114_INVALID_PORT_DEFAULT_VALUE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "TreeNodesModel port defaults must match the declared type.";
+    };
+    readonly "model/require-output-port-remap": {
+        readonly code: "BT115_OUTPUT_PORT_REQUIRES_REMAP";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Resolved output ports must write to a blackboard remap.";
+    };
+    readonly "model/no-childless-control-shape-mismatch": {
+        readonly code: "BT108_CHILD_CAPABLE_NODE_SELF_CLOSING";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Control and decorator nodes should normally use open/close tags.";
+    };
+    readonly "model/no-leaf-block-shape": {
+        readonly code: "BT109_LEAF_NODE_OPEN_CLOSE";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Leaf nodes should normally be self-closing unless they contain child nodes.";
+    };
+    readonly "model/valid-child-count": {
+        readonly code: "BT110_INVALID_CHILD_COUNT";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Child count must match the expected count for the node kind (Action/Condition: 0, Decorator: 1, Control: >=1, special builtins: fixed range).";
+    };
+    readonly "model/no-conflicting-definition": {
+        readonly code: "BT012_CONFLICTING_NODE_MODEL";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Node model definitions must agree on kind and port shape.";
+    };
+    readonly "suppression/no-unused": {
+        readonly code: "BT351_UNUSED_SUPPRESSION";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Suppressions should match at least one diagnostic.";
+    };
+    readonly "suppression/require-reason": {
+        readonly code: "BT353_MISSING_SUPPRESSION_REASON";
+        readonly defaultSeverity: ConfigSeverity;
+        readonly description: "Suppressions should include a reason when required.";
+    };
+};
+type RuleName = keyof typeof RULES;
+type DiagnosticCode = (typeof RULES)[RuleName]["code"];
+
+declare const RuleCodes: {
+    readonly InvalidScriptSyntax: "BT401_INVALID_SCRIPT_SYNTAX";
+    readonly EmptyScript: "BT402_EMPTY_SCRIPT";
+    readonly InvalidScriptToken: "BT403_INVALID_SCRIPT_TOKEN";
+    readonly UnknownScriptVariable: "BT404_UNKNOWN_SCRIPT_VARIABLE";
+    readonly AssignmentToUnknownVariable: "BT405_ASSIGNMENT_TO_UNKNOWN_VARIABLE";
+    readonly InvalidCompoundAssignment: "BT406_INVALID_COMPOUND_ASSIGNMENT";
+    readonly InvalidScriptOperandType: "BT407_INVALID_SCRIPT_OPERAND_TYPE";
+    readonly ScriptResultNotBoolCompatible: "BT408_SCRIPT_RESULT_NOT_BOOL_COMPATIBLE";
+    readonly ScriptVariableTypeMismatch: "BT410_SCRIPT_VARIABLE_TYPE_MISMATCH";
+    readonly InvalidRootElement: "BT001_INVALID_ROOT_ELEMENT";
+    readonly MissingBTCPPFormat: "BT002_MISSING_BTCPP_FORMAT";
+    readonly MissingBehaviorTreeID: "BT003_MISSING_BEHAVIOR_TREE_ID";
+    readonly DuplicateBehaviorTreeID: "BT004_DUPLICATE_BEHAVIOR_TREE_ID";
+    readonly UnknownSubTree: "BT005_UNKNOWN_SUBTREE";
+    readonly DuplicateNodeModelId: "BT006_DUPLICATE_NODE_MODEL_ID";
+    readonly MissingPortName: "BT007_MISSING_PORT_NAME";
+    readonly DuplicatePortName: "BT008_DUPLICATE_PORT_NAME";
+    readonly UnknownTopLevelElement: "BT009_UNKNOWN_TOP_LEVEL_ELEMENT";
+    readonly UnknownMainTree: "BT010_UNKNOWN_MAIN_TREE";
+    readonly AmbiguousSubTree: "BT011_AMBIGUOUS_SUBTREE";
+    readonly ConflictingNodeModel: "BT012_CONFLICTING_NODE_MODEL";
+    readonly DuplicateBehaviorTreeIdInWorkspace: "BT013_DUPLICATE_BEHAVIOR_TREE_ID_IN_WORKSPACE";
+    readonly MissingIncludePath: "BT301_MISSING_INCLUDE_PATH";
+    readonly IncludeNotFound: "BT302_INCLUDE_NOT_FOUND";
+    readonly IncludeCycle: "BT303_INCLUDE_CYCLE";
+    readonly UnresolvedIncludePathVariable: "BT304_UNRESOLVED_INCLUDE_PATH_VARIABLE";
+    readonly IncludeOutsideWorkspace: "BT306_INCLUDE_OUTSIDE_WORKSPACE";
+    readonly ExternalIncludeUsed: "BT307_EXTERNAL_INCLUDE_USED";
+    readonly IncludeDepthExceeded: "BT309_INCLUDE_DEPTH_EXCEEDED";
+    readonly TooManyResolvedFiles: "BT310_TOO_MANY_RESOLVED_FILES";
+    readonly EntrypointNotFound: "BT311_ENTRYPOINT_NOT_FOUND";
+    readonly RosPackageResolverMissing: "BT312_ROS_PACKAGE_RESOLVER_MISSING";
+    readonly RosPackageNotFound: "BT313_ROS_PACKAGE_NOT_FOUND";
+    readonly UnknownNode: "BT105_UNKNOWN_NODE";
+    readonly MissingRequiredPort: "BT101_MISSING_REQUIRED_PORT";
+    readonly UnknownPort: "BT102_UNKNOWN_PORT";
+    readonly InvalidPortValueType: "BT103_INVALID_PORT_VALUE_TYPE";
+    readonly ChildCapableNodeSelfClosing: "BT108_CHILD_CAPABLE_NODE_SELF_CLOSING";
+    readonly LeafNodeOpenClose: "BT109_LEAF_NODE_OPEN_CLOSE";
+    readonly InvalidChildCount: "BT110_INVALID_CHILD_COUNT";
+    readonly BlackboardTypeMismatch: "BT111_BLACKBOARD_TYPE_MISMATCH";
+    readonly CustomLiteralRequiresValidator: "BT112_CUSTOM_LITERAL_REQUIRES_VALIDATOR";
+    readonly InvalidPortDefaultValue: "BT114_INVALID_PORT_DEFAULT_VALUE";
+    readonly OutputPortRequiresRemap: "BT115_OUTPUT_PORT_REQUIRES_REMAP";
+    readonly InvalidPortName: "BT116_INVALID_PORT_NAME";
+    readonly AugmentTargetNotFound: "BT117_AUGMENT_TARGET_NOT_FOUND";
+    readonly AugmentPortNotFound: "BT118_AUGMENT_PORT_NOT_FOUND";
+    readonly InvalidTypeRefinement: "BT119_INVALID_TYPE_REFINEMENT";
+    readonly ExternalModelFileNotFound: "BT321_EXTERNAL_MODEL_FILE_NOT_FOUND";
+    readonly AugmentationFileNotFound: "BT324_AUGMENTATION_FILE_NOT_FOUND";
+    readonly MissingTreeNodesModel: "BT322_MISSING_TREENODESMODEL";
+    readonly ExternalModelXmlParseError: "BT323_EXTERNAL_MODEL_XML_PARSE_ERROR";
+    readonly NodeDefinitionFileNotFound: "BT331_NODE_DEFINITION_FILE_NOT_FOUND";
+    readonly InvalidNodeDefinitionJson: "BT332_INVALID_NODE_DEFINITION_JSON";
+    readonly InvalidNodeDefinitionSchema: "BT333_INVALID_NODE_DEFINITION_SCHEMA";
+    readonly DuplicateNodeDefinitionId: "BT334_DUPLICATE_NODE_DEFINITION_ID";
+    readonly InvalidAugmentationJson: "BT335_INVALID_AUGMENTATION_JSON";
+    readonly InvalidAugmentationSchema: "BT336_INVALID_AUGMENTATION_SCHEMA";
+    readonly ConflictingPortDefault: "BT107_CONFLICTING_PORT_DEFAULT";
+    readonly UnusedSuppression: "BT351_UNUSED_SUPPRESSION";
+    readonly MissingSuppressionReason: "BT353_MISSING_SUPPRESSION_REASON";
+};
+declare const RULE_CODES: ("BT006_DUPLICATE_NODE_MODEL_ID" | "BT401_INVALID_SCRIPT_SYNTAX" | "BT402_EMPTY_SCRIPT" | "BT403_INVALID_SCRIPT_TOKEN" | "BT404_UNKNOWN_SCRIPT_VARIABLE" | "BT405_ASSIGNMENT_TO_UNKNOWN_VARIABLE" | "BT406_INVALID_COMPOUND_ASSIGNMENT" | "BT407_INVALID_SCRIPT_OPERAND_TYPE" | "BT408_SCRIPT_RESULT_NOT_BOOL_COMPATIBLE" | "BT410_SCRIPT_VARIABLE_TYPE_MISMATCH" | "BT001_INVALID_ROOT_ELEMENT" | "BT002_MISSING_BTCPP_FORMAT" | "BT003_MISSING_BEHAVIOR_TREE_ID" | "BT004_DUPLICATE_BEHAVIOR_TREE_ID" | "BT005_UNKNOWN_SUBTREE" | "BT007_MISSING_PORT_NAME" | "BT008_DUPLICATE_PORT_NAME" | "BT009_UNKNOWN_TOP_LEVEL_ELEMENT" | "BT010_UNKNOWN_MAIN_TREE" | "BT011_AMBIGUOUS_SUBTREE" | "BT012_CONFLICTING_NODE_MODEL" | "BT013_DUPLICATE_BEHAVIOR_TREE_ID_IN_WORKSPACE" | "BT301_MISSING_INCLUDE_PATH" | "BT302_INCLUDE_NOT_FOUND" | "BT303_INCLUDE_CYCLE" | "BT304_UNRESOLVED_INCLUDE_PATH_VARIABLE" | "BT306_INCLUDE_OUTSIDE_WORKSPACE" | "BT307_EXTERNAL_INCLUDE_USED" | "BT309_INCLUDE_DEPTH_EXCEEDED" | "BT310_TOO_MANY_RESOLVED_FILES" | "BT311_ENTRYPOINT_NOT_FOUND" | "BT312_ROS_PACKAGE_RESOLVER_MISSING" | "BT313_ROS_PACKAGE_NOT_FOUND" | "BT105_UNKNOWN_NODE" | "BT101_MISSING_REQUIRED_PORT" | "BT102_UNKNOWN_PORT" | "BT103_INVALID_PORT_VALUE_TYPE" | "BT108_CHILD_CAPABLE_NODE_SELF_CLOSING" | "BT109_LEAF_NODE_OPEN_CLOSE" | "BT110_INVALID_CHILD_COUNT" | "BT111_BLACKBOARD_TYPE_MISMATCH" | "BT112_CUSTOM_LITERAL_REQUIRES_VALIDATOR" | "BT114_INVALID_PORT_DEFAULT_VALUE" | "BT115_OUTPUT_PORT_REQUIRES_REMAP" | "BT116_INVALID_PORT_NAME" | "BT117_AUGMENT_TARGET_NOT_FOUND" | "BT118_AUGMENT_PORT_NOT_FOUND" | "BT119_INVALID_TYPE_REFINEMENT" | "BT321_EXTERNAL_MODEL_FILE_NOT_FOUND" | "BT324_AUGMENTATION_FILE_NOT_FOUND" | "BT322_MISSING_TREENODESMODEL" | "BT323_EXTERNAL_MODEL_XML_PARSE_ERROR" | "BT331_NODE_DEFINITION_FILE_NOT_FOUND" | "BT332_INVALID_NODE_DEFINITION_JSON" | "BT333_INVALID_NODE_DEFINITION_SCHEMA" | "BT334_DUPLICATE_NODE_DEFINITION_ID" | "BT335_INVALID_AUGMENTATION_JSON" | "BT336_INVALID_AUGMENTATION_SCHEMA" | "BT107_CONFLICTING_PORT_DEFAULT" | "BT351_UNUSED_SUPPRESSION" | "BT353_MISSING_SUPPRESSION_REASON")[];
+
+declare function getNodeUsagePolicyForRules(config: EffectiveFileConfig): Partial<NodeUsagePolicy>;
+
+declare function isRuleName(value: string): value is RuleName;
+declare function getRuleNameForCode(code: string): RuleName | undefined;
+declare function getDiagnosticCodeForRule(rule: RuleName): string;
+declare function normalizeRuleConfig(input: unknown): {
+    severity: ConfigSeverity;
+    options?: Record<string, unknown>;
+} | null;
+declare function getRuleSeverity(rules: Record<string, unknown>, rule: RuleName): ConfigSeverity;
+declare function validateRuleOptions(rule: RuleName, options: Record<string, unknown>): ReturnType<typeof createDiagnostic>[];
+
+declare function validateRawConfigRules(raw: RawBtxmlConfig): ConfigDiagnostic[];
+
+type RuleMetadataDefaultSeverity = ConfigSeverity | DiagnosticSeverity;
+type RuleMetadata = {
+    code: string;
+    defaultSeverity: RuleMetadataDefaultSeverity;
+    title: string;
+    description: string;
+    invalidExample?: string;
+    validExample?: string;
+    fix?: string;
+    suppressible: boolean;
+    configExample?: string;
+    options?: RuleOptionDoc[];
+};
+declare function findRuleMetadata(code: string): RuleMetadata;
+declare function getRuleMetadata(value: string): RuleMetadata;
+declare function listRuleCodes(): ("BT006_DUPLICATE_NODE_MODEL_ID" | "BT401_INVALID_SCRIPT_SYNTAX" | "BT402_EMPTY_SCRIPT" | "BT403_INVALID_SCRIPT_TOKEN" | "BT404_UNKNOWN_SCRIPT_VARIABLE" | "BT405_ASSIGNMENT_TO_UNKNOWN_VARIABLE" | "BT406_INVALID_COMPOUND_ASSIGNMENT" | "BT407_INVALID_SCRIPT_OPERAND_TYPE" | "BT408_SCRIPT_RESULT_NOT_BOOL_COMPATIBLE" | "BT410_SCRIPT_VARIABLE_TYPE_MISMATCH" | "BT001_INVALID_ROOT_ELEMENT" | "BT002_MISSING_BTCPP_FORMAT" | "BT003_MISSING_BEHAVIOR_TREE_ID" | "BT004_DUPLICATE_BEHAVIOR_TREE_ID" | "BT005_UNKNOWN_SUBTREE" | "BT007_MISSING_PORT_NAME" | "BT008_DUPLICATE_PORT_NAME" | "BT009_UNKNOWN_TOP_LEVEL_ELEMENT" | "BT010_UNKNOWN_MAIN_TREE" | "BT011_AMBIGUOUS_SUBTREE" | "BT012_CONFLICTING_NODE_MODEL" | "BT013_DUPLICATE_BEHAVIOR_TREE_ID_IN_WORKSPACE" | "BT301_MISSING_INCLUDE_PATH" | "BT302_INCLUDE_NOT_FOUND" | "BT303_INCLUDE_CYCLE" | "BT304_UNRESOLVED_INCLUDE_PATH_VARIABLE" | "BT306_INCLUDE_OUTSIDE_WORKSPACE" | "BT307_EXTERNAL_INCLUDE_USED" | "BT309_INCLUDE_DEPTH_EXCEEDED" | "BT310_TOO_MANY_RESOLVED_FILES" | "BT311_ENTRYPOINT_NOT_FOUND" | "BT312_ROS_PACKAGE_RESOLVER_MISSING" | "BT313_ROS_PACKAGE_NOT_FOUND" | "BT105_UNKNOWN_NODE" | "BT101_MISSING_REQUIRED_PORT" | "BT102_UNKNOWN_PORT" | "BT103_INVALID_PORT_VALUE_TYPE" | "BT108_CHILD_CAPABLE_NODE_SELF_CLOSING" | "BT109_LEAF_NODE_OPEN_CLOSE" | "BT110_INVALID_CHILD_COUNT" | "BT111_BLACKBOARD_TYPE_MISMATCH" | "BT112_CUSTOM_LITERAL_REQUIRES_VALIDATOR" | "BT114_INVALID_PORT_DEFAULT_VALUE" | "BT115_OUTPUT_PORT_REQUIRES_REMAP" | "BT116_INVALID_PORT_NAME" | "BT117_AUGMENT_TARGET_NOT_FOUND" | "BT118_AUGMENT_PORT_NOT_FOUND" | "BT119_INVALID_TYPE_REFINEMENT" | "BT321_EXTERNAL_MODEL_FILE_NOT_FOUND" | "BT324_AUGMENTATION_FILE_NOT_FOUND" | "BT322_MISSING_TREENODESMODEL" | "BT323_EXTERNAL_MODEL_XML_PARSE_ERROR" | "BT331_NODE_DEFINITION_FILE_NOT_FOUND" | "BT332_INVALID_NODE_DEFINITION_JSON" | "BT333_INVALID_NODE_DEFINITION_SCHEMA" | "BT334_DUPLICATE_NODE_DEFINITION_ID" | "BT335_INVALID_AUGMENTATION_JSON" | "BT336_INVALID_AUGMENTATION_SCHEMA" | "BT107_CONFLICTING_PORT_DEFAULT" | "BT351_UNUSED_SUPPRESSION" | "BT353_MISSING_SUPPRESSION_REASON")[];
+declare function listRuleSlugs(): string[];
+declare function listRules(): Array<{
+    name: RuleName;
+    metadata: RuleMetadata;
+}>;
+
+export { type DiagnosticCode, RULES, RULE_CODES, RuleCodes, type RuleMetadata, type RuleMetadataDefaultSeverity, type RuleName, type RuleOptionDoc, type RuleRegistryEntry, findRuleMetadata, getDiagnosticCodeForRule, getNodeUsagePolicyForRules, getRuleMetadata, getRuleNameForCode, getRuleSeverity, isRuleName, listRuleCodes, listRuleSlugs, listRules, normalizeRuleConfig, validateRawConfigRules, validateRuleOptions };

package/dist/rules.js

@@ -0,0 +1,5 @@
+import{z as p}from"zod";var e={InvalidScriptSyntax:"BT401_INVALID_SCRIPT_SYNTAX",EmptyScript:"BT402_EMPTY_SCRIPT",InvalidScriptToken:"BT403_INVALID_SCRIPT_TOKEN",UnknownScriptVariable:"BT404_UNKNOWN_SCRIPT_VARIABLE",AssignmentToUnknownVariable:"BT405_ASSIGNMENT_TO_UNKNOWN_VARIABLE",InvalidCompoundAssignment:"BT406_INVALID_COMPOUND_ASSIGNMENT",InvalidScriptOperandType:"BT407_INVALID_SCRIPT_OPERAND_TYPE",ScriptResultNotBoolCompatible:"BT408_SCRIPT_RESULT_NOT_BOOL_COMPATIBLE",ScriptVariableTypeMismatch:"BT410_SCRIPT_VARIABLE_TYPE_MISMATCH",InvalidRootElement:"BT001_INVALID_ROOT_ELEMENT",MissingBTCPPFormat:"BT002_MISSING_BTCPP_FORMAT",MissingBehaviorTreeID:"BT003_MISSING_BEHAVIOR_TREE_ID",DuplicateBehaviorTreeID:"BT004_DUPLICATE_BEHAVIOR_TREE_ID",UnknownSubTree:"BT005_UNKNOWN_SUBTREE",DuplicateNodeModelId:"BT006_DUPLICATE_NODE_MODEL_ID",MissingPortName:"BT007_MISSING_PORT_NAME",DuplicatePortName:"BT008_DUPLICATE_PORT_NAME",UnknownTopLevelElement:"BT009_UNKNOWN_TOP_LEVEL_ELEMENT",UnknownMainTree:"BT010_UNKNOWN_MAIN_TREE",AmbiguousSubTree:"BT011_AMBIGUOUS_SUBTREE",ConflictingNodeModel:"BT012_CONFLICTING_NODE_MODEL",DuplicateBehaviorTreeIdInWorkspace:"BT013_DUPLICATE_BEHAVIOR_TREE_ID_IN_WORKSPACE",MissingIncludePath:"BT301_MISSING_INCLUDE_PATH",IncludeNotFound:"BT302_INCLUDE_NOT_FOUND",IncludeCycle:"BT303_INCLUDE_CYCLE",UnresolvedIncludePathVariable:"BT304_UNRESOLVED_INCLUDE_PATH_VARIABLE",IncludeOutsideWorkspace:"BT306_INCLUDE_OUTSIDE_WORKSPACE",ExternalIncludeUsed:"BT307_EXTERNAL_INCLUDE_USED",IncludeDepthExceeded:"BT309_INCLUDE_DEPTH_EXCEEDED",TooManyResolvedFiles:"BT310_TOO_MANY_RESOLVED_FILES",EntrypointNotFound:"BT311_ENTRYPOINT_NOT_FOUND",RosPackageResolverMissing:"BT312_ROS_PACKAGE_RESOLVER_MISSING",RosPackageNotFound:"BT313_ROS_PACKAGE_NOT_FOUND",UnknownNode:"BT105_UNKNOWN_NODE",MissingRequiredPort:"BT101_MISSING_REQUIRED_PORT",UnknownPort:"BT102_UNKNOWN_PORT",InvalidPortValueType:"BT103_INVALID_PORT_VALUE_TYPE",ChildCapableNodeSelfClosing:"BT108_CHILD_CAPABLE_NODE_SELF_CLOSING",LeafNodeOpenClose:"BT109_LEAF_NODE_OPEN_CLOSE",InvalidChildCount:"BT110_INVALID_CHILD_COUNT",BlackboardTypeMismatch:"BT111_BLACKBOARD_TYPE_MISMATCH",CustomLiteralRequiresValidator:"BT112_CUSTOM_LITERAL_REQUIRES_VALIDATOR",InvalidPortDefaultValue:"BT114_INVALID_PORT_DEFAULT_VALUE",OutputPortRequiresRemap:"BT115_OUTPUT_PORT_REQUIRES_REMAP",InvalidPortName:"BT116_INVALID_PORT_NAME",AugmentTargetNotFound:"BT117_AUGMENT_TARGET_NOT_FOUND",AugmentPortNotFound:"BT118_AUGMENT_PORT_NOT_FOUND",InvalidTypeRefinement:"BT119_INVALID_TYPE_REFINEMENT",ExternalModelFileNotFound:"BT321_EXTERNAL_MODEL_FILE_NOT_FOUND",AugmentationFileNotFound:"BT324_AUGMENTATION_FILE_NOT_FOUND",MissingTreeNodesModel:"BT322_MISSING_TREENODESMODEL",ExternalModelXmlParseError:"BT323_EXTERNAL_MODEL_XML_PARSE_ERROR",NodeDefinitionFileNotFound:"BT331_NODE_DEFINITION_FILE_NOT_FOUND",InvalidNodeDefinitionJson:"BT332_INVALID_NODE_DEFINITION_JSON",InvalidNodeDefinitionSchema:"BT333_INVALID_NODE_DEFINITION_SCHEMA",DuplicateNodeDefinitionId:"BT334_DUPLICATE_NODE_DEFINITION_ID",InvalidAugmentationJson:"BT335_INVALID_AUGMENTATION_JSON",InvalidAugmentationSchema:"BT336_INVALID_AUGMENTATION_SCHEMA",ConflictingPortDefault:"BT107_CONFLICTING_PORT_DEFAULT",UnusedSuppression:"BT351_UNUSED_SUPPRESSION",MissingSuppressionReason:"BT353_MISSING_SUPPRESSION_REASON"},T=Object.values(e).sort();var P=p.object({subTreePorts:p.enum(["loose","strict"]).optional()}).strict(),A=p.object({allowStringEntryCompatibility:p.boolean().optional()}).strict(),s={"script/valid-syntax":{code:e.InvalidScriptSyntax,defaultSeverity:"error",description:"Script-bearing attributes must parse as valid BT.CPP scripts."},"script/no-unknown-variable":{code:e.UnknownScriptVariable,defaultSeverity:"warn",description:"Script-bearing attributes should not reference unknown variables."},"script/valid-assignment":{code:e.AssignmentToUnknownVariable,codes:[e.AssignmentToUnknownVariable,e.InvalidCompoundAssignment,e.ScriptVariableTypeMismatch],defaultSeverity:"error",description:"Script assignments must target known variables and use compatible types."},"script/valid-expression-type":{code:e.InvalidScriptOperandType,defaultSeverity:"error",description:"Script expressions must use operators with compatible operand types."},"script/valid-result-type":{code:e.ScriptResultNotBoolCompatible,defaultSeverity:"error",description:"Condition-style script attributes must have a bool-compatible inferred result."},"xml/valid-root":{code:e.InvalidRootElement,defaultSeverity:"error",description:"Root element must be <root>."},"xml/require-btcpp-format":{code:e.MissingBTCPPFormat,defaultSeverity:"warn",description:'Root element must declare BTCPP_format="4".'},"tree/require-id":{code:e.MissingBehaviorTreeID,defaultSeverity:"error",description:"BehaviorTree elements require an ID attribute."},"tree/no-duplicate-id-in-file":{code:e.DuplicateBehaviorTreeID,defaultSeverity:"error",description:"BehaviorTree IDs must be unique within a file."},"tree/no-duplicate-id":{code:e.DuplicateBehaviorTreeIdInWorkspace,defaultSeverity:"error",description:"BehaviorTree IDs must be unique across the workspace."},"tree/no-unknown-subtree":{code:e.UnknownSubTree,defaultSeverity:"error",description:"A SubTree must resolve to a BehaviorTree or a configured model."},"tree/no-unknown-main-tree":{code:e.UnknownMainTree,defaultSeverity:"error",description:"main_tree_to_execute must reference a known BehaviorTree."},"tree/no-ambiguous-subtree":{code:e.AmbiguousSubTree,defaultSeverity:"error",description:"SubTree references must resolve to a single definition."},"tree/no-duplicate-node-model-id":{code:e.DuplicateNodeModelId,defaultSeverity:"error",description:"TreeNodesModel elements must have unique IDs within the same model block."},"xml/no-unknown-top-level-element":{code:e.UnknownTopLevelElement,defaultSeverity:"warn",description:"Top-level elements must be BehaviorTree, TreeNodesModel, or configured include elements."},"include/require-path":{code:e.MissingIncludePath,defaultSeverity:"error",description:"include elements require a path attribute."},"include/no-missing-file":{code:e.IncludeNotFound,defaultSeverity:"error",description:"Referenced include file does not exist."},"include/no-cycle":{code:e.IncludeCycle,defaultSeverity:"error",description:"Include graph cycles are not allowed."},"include/no-outside-root":{code:e.IncludeOutsideWorkspace,defaultSeverity:"error",description:"Includes must stay within the workspace root."},"include/no-unresolved-variable":{code:e.UnresolvedIncludePathVariable,defaultSeverity:"error",description:"Include path variables must resolve before lookup."},"include/no-depth-exceeded":{code:e.IncludeDepthExceeded,defaultSeverity:"error",description:"Include resolution must stay within the configured maximum depth."},"include/no-too-many-files":{code:e.TooManyResolvedFiles,defaultSeverity:"error",description:"Include resolution must stay within the configured file limit."},"include/require-ros-package-resolver":{code:e.RosPackageResolverMissing,defaultSeverity:"error",description:"When include uses ros_pkg, a host resolvePackageUri capability must be provided."},"include/no-missing-ros-package":{code:e.RosPackageNotFound,defaultSeverity:"error",description:"ros_pkg include must resolve to an existing ROS package root URI."},"include/report-external-used":{code:e.ExternalIncludeUsed,defaultSeverity:"info",description:"Reports when an allowed include resolves outside the workspace root."},"model/no-unknown-node":{code:e.UnknownNode,defaultSeverity:"warn",description:"Node usages must resolve to a known model."},"model/require-port":{code:e.MissingRequiredPort,defaultSeverity:"error",description:"Required ports must be supplied."},"model/require-port-name":{code:e.MissingPortName,defaultSeverity:"error",description:"Port elements require a name attribute."},"model/no-duplicate-port-name":{code:e.DuplicatePortName,defaultSeverity:"error",description:"Ports with the same name are not allowed."},"model/valid-port-name":{code:e.InvalidPortName,defaultSeverity:"error",description:"Port names must be valid XML attribute names for BT nodes."},"model/no-unknown-port":{code:e.UnknownPort,defaultSeverity:"warn",optionsSchema:P,options:[{name:"subTreePorts",type:'"loose" | "strict"',default:"loose",description:"Controls whether SubTree remap attributes are checked strictly."}],description:"Reports ports that are not declared by the resolved node model."},"model/valid-port-value":{code:e.InvalidPortValueType,defaultSeverity:"error",description:"Port values must match the declared type."},"model/no-blackboard-type-mismatch":{code:e.BlackboardTypeMismatch,defaultSeverity:"error",optionsSchema:A,options:[{name:"allowStringEntryCompatibility",type:"boolean",default:"true",description:"Treat std::string blackboard entries as runtime-compatible with other port types, matching BT.CPP's existing-entry special case."}],description:"Blackboard entries must not mix incompatible resolved port types."},"model/valid-port-default-value":{code:e.InvalidPortDefaultValue,defaultSeverity:"error",description:"TreeNodesModel port defaults must match the declared type."},"model/require-output-port-remap":{code:e.OutputPortRequiresRemap,defaultSeverity:"warn",description:"Resolved output ports must write to a blackboard remap."},"model/no-childless-control-shape-mismatch":{code:e.ChildCapableNodeSelfClosing,defaultSeverity:"warn",description:"Control and decorator nodes should normally use open/close tags."},"model/no-leaf-block-shape":{code:e.LeafNodeOpenClose,defaultSeverity:"warn",description:"Leaf nodes should normally be self-closing unless they contain child nodes."},"model/valid-child-count":{code:e.InvalidChildCount,defaultSeverity:"warn",description:"Child count must match the expected count for the node kind (Action/Condition: 0, Decorator: 1, Control: >=1, special builtins: fixed range)."},"model/no-conflicting-definition":{code:e.ConflictingNodeModel,defaultSeverity:"error",description:"Node model definitions must agree on kind and port shape."},"suppression/no-unused":{code:e.UnusedSuppression,defaultSeverity:"warn",description:"Suppressions should match at least one diagnostic."},"suppression/require-reason":{code:e.MissingSuppressionReason,defaultSeverity:"off",description:"Suppressions should include a reason when required."}};var m=["off","info","warn","error"];var f={Error:"error",Warning:"warning",Info:"info"};function g(t,o,i,r,a="",l,d){return{code:t,severity:o,message:i,uri:a,...r?{range:r}:{},...l?{details:l}:{},...d?{data:d}:{}}}function I(t){let o=t.linter.rules["model/no-unknown-port"];return Array.isArray(o)&&o.length>=2&&o[1].subTreePorts==="strict"?{unknownSubTreePorts:"reject"}:{unknownSubTreePorts:"allow"}}function v(t){return t in s}function _(t){for(let[o,i]of Object.entries(s)){let r=i;if(r.code===t||r.codes?.includes(t))return o}}function x(t){return s[t].code}function u(t){if(typeof t=="string")return m.includes(t)?{severity:t}:null;if(Array.isArray(t)&&t.length>=1&&t.length<=2){let[o,i]=t;if(typeof o=="string"&&m.includes(o)&&(i===void 0||typeof i=="object"&&i!==null&&!Array.isArray(i))){let r={severity:o};return i!==void 0&&(r.options=i),r}}return null}function h(t,o){let i=t[o];if(i!==void 0){let r=u(i);if(r)return r.severity}return s[o].defaultSeverity}function y(t,o){let i=[],a=s[t].optionsSchema;if(!a)return i;let l=a.safeParse(o);if(l.success)return i;for(let d of l.error.issues)i.push(...k(t,d));return i}function k(t,o){if(o.code==="unrecognized_keys")return o.keys.map(r=>g("CFG011_INVALID_RULE_OPTION",f.Error,`unknown option \`${String(r)}\` for rule \`${t}\``,void 0,void 0,{help:N(t)}));let i=typeof o.path[0]=="string"?o.path[0]:void 0;return[g("CFG011_INVALID_RULE_OPTION",f.Error,i?`invalid option \`${i}\`: ${o.message}`:`invalid options for rule \`${t}\`: ${o.message}`,void 0,void 0,{help:N(t)})]}function N(t){let i=s[t].options?.map(r=>r.name)??[];return i.length>0?`valid options are: ${i.join(", ")}`:void 0}function b(t){let o=[];D(t.linter,"linter.rules",o);for(let[i,r]of(t.overrides??[]).entries())D(r.linter,`overrides.${i}.linter.rules`,o);return o}function D(t,o,i){for(let[r,a]of Object.entries(t?.rules??{})){let l=`${o}.${r}`;if(!v(r)){i.push({code:"CFG010_UNKNOWN_RULE",severity:"error",path:l,message:`unknown lint rule \`${r}\``,help:"see docs/rules.md for a list of valid rule names"});continue}let d=u(a);if(d?.options)for(let E of y(r,d.options))i.push({code:"CFG011_INVALID_RULE_OPTION",severity:"error",path:B(l,d.options,E.message),message:E.message,help:E.details?.help})}}function B(t,o,i){let r=Object.keys(o).find(a=>i.includes(`\`${a}\``));return r?`${t}.1.${r}`:`${t}.1`}var n=(t,o,i,r=!0)=>({code:t,title:o,description:i,suppressible:r}),U={[e.InvalidScriptSyntax]:{code:e.InvalidScriptSyntax,title:"Invalid script syntax",description:"Script-bearing attributes must parse as valid BT.CPP scripts.",suppressible:!0,invalidExample:'<AlwaysSuccess _successIf="A +"/>',validExample:'<AlwaysSuccess _successIf="A == 1"/>',configExample:'{"linter":{"rules":{"script/valid-syntax":"error"}}}'},[e.EmptyScript]:{code:e.EmptyScript,title:"Empty script",description:"Script-bearing attributes must not be empty.",suppressible:!0,invalidExample:'<AlwaysSuccess _successIf=""/>',validExample:'<AlwaysSuccess _successIf="true"/>',configExample:'{"linter":{"rules":{"script/valid-syntax":"error"}}}'},[e.InvalidScriptToken]:{code:e.InvalidScriptToken,title:"Invalid script token",description:"Script-bearing attributes must not contain invalid BT.CPP tokens.",suppressible:!0,invalidExample:'<Script code="0x"/>',validExample:'<Script code="value := 0x10"/>',configExample:'{"linter":{"rules":{"script/valid-syntax":"error"}}}'},[e.UnknownScriptVariable]:{code:e.UnknownScriptVariable,title:"Unknown script variable",description:"Script-bearing attributes should not read blackboard or local variables that were never introduced.",suppressible:!0,invalidExample:'<AlwaysSuccess _successIf="missing == 1"/>',validExample:'<Script code="count := 1; done = count"/>',configExample:'{"linter":{"rules":{"script/no-unknown-variable":"warn"}}}'},[e.AssignmentToUnknownVariable]:{code:e.AssignmentToUnknownVariable,title:"Assignment to unknown script variable",description:"Assignments with `=` or compound operators must target an existing script or blackboard variable.",suppressible:!0,invalidExample:'<Script code="count = 1"/>',validExample:'<Script code="count := 1; count = 2"/>',configExample:'{"linter":{"rules":{"script/valid-assignment":"error"}}}'},[e.InvalidCompoundAssignment]:{code:e.InvalidCompoundAssignment,title:"Invalid compound assignment",description:"Compound assignment operators must be used with supported operand types (`number` or `string` for `+=`, numbers only otherwise).",suppressible:!0,invalidExample:'<Script code="name := "x"; name -= 1"/>',validExample:'<Script code="count := 1; count += 2"/>',configExample:'{"linter":{"rules":{"script/valid-assignment":"error"}}}'},[e.InvalidScriptOperandType]:{code:e.InvalidScriptOperandType,title:"Invalid script operand type",description:"Script operators and ternary conditions must be applied to operands with compatible inferred types.",suppressible:!0,invalidExample:`<AlwaysSuccess _successIf="'x' * 2"/>`,validExample:'<AlwaysSuccess _successIf="count * 2 > 0"/>',configExample:'{"linter":{"rules":{"script/valid-expression-type":"error"}}}'},[e.ScriptResultNotBoolCompatible]:{code:e.ScriptResultNotBoolCompatible,title:"Script result is not bool-compatible",description:"Condition-style script attributes must end in an inferred bool-compatible result type.",suppressible:!0,invalidExample:`<AlwaysSuccess _successIf="'hello'"/>`,validExample:'<AlwaysSuccess _successIf="true"/>',configExample:'{"linter":{"rules":{"script/valid-result-type":"error"}}}'},[e.ScriptVariableTypeMismatch]:{code:e.ScriptVariableTypeMismatch,title:"Script variable type mismatch",description:"Script assignments must not write an incompatible inferred type into an existing variable.",suppressible:!0,invalidExample:'<Script code="count := 1; count = "x""/>',validExample:'<Script code="count := 1; count = 2"/>',configExample:'{"linter":{"rules":{"script/valid-assignment":"error"}}}'},[e.InvalidRootElement]:n(e.InvalidRootElement,"Invalid root element","Root element must be <root>.",!1),[e.MissingBTCPPFormat]:n(e.MissingBTCPPFormat,"Missing BTCPP format",'Root element must declare BTCPP_format="4".',!1),[e.MissingBehaviorTreeID]:n(e.MissingBehaviorTreeID,"Missing BehaviorTree ID","BehaviorTree elements require an ID attribute.",!1),[e.DuplicateBehaviorTreeID]:n(e.DuplicateBehaviorTreeID,"Duplicate BehaviorTree ID","BehaviorTree IDs must be unique within a file.",!1),[e.UnknownSubTree]:{code:e.UnknownSubTree,title:"Unknown SubTree reference",description:"A SubTree must resolve to a BehaviorTree or a configured model.",suppressible:!0,invalidExample:'<SubTree ID="missing_tree"/>',validExample:'<BehaviorTree ID="missing_tree"><Sequence/></BehaviorTree>',fix:"Define the BehaviorTree, add an external TreeNodesModel file, or add a nodes config entry.",configExample:'{"linter":{"rules":{"tree/no-unknown-subtree":"warn"}}}'},[e.DuplicateNodeModelId]:n(e.DuplicateNodeModelId,"Duplicate node model ID in TreeNodesModel","TreeNodesModel elements must have unique IDs within the same model block.",!1),[e.MissingPortName]:n(e.MissingPortName,"Missing port name","Port elements require a name attribute.",!1),[e.DuplicatePortName]:n(e.DuplicatePortName,"Duplicate port name","Ports with the same name are not allowed.",!1),[e.InvalidPortName]:{code:e.InvalidPortName,title:"Invalid port name",description:"Port names must be valid XML attribute names for BT nodes.",suppressible:!1,invalidExample:'<input_port name="request.name" type="string"/>',validExample:'<input_port name="request_name" type="string"/>',fix:"Rename the port so it does not use reserved names, leading digits, whitespace, control characters, or XML/path punctuation.",configExample:'{"linter":{"rules":{"model/valid-port-name":"warn"}}}'},[e.UnknownTopLevelElement]:n(e.UnknownTopLevelElement,"Unknown top-level element","Top-level elements must be BehaviorTree, TreeNodesModel, or configured include elements.",!1),[e.UnknownMainTree]:n(e.UnknownMainTree,"Unknown main tree","main_tree_to_execute must reference a known BehaviorTree.",!1),[e.AmbiguousSubTree]:n(e.AmbiguousSubTree,"Ambiguous SubTree","SubTree references must resolve to a single definition.",!1),[e.ConflictingNodeModel]:{code:e.ConflictingNodeModel,title:"Conflicting node model",description:"Node model definitions must agree on kind and port shape.",suppressible:!1,fix:"Run `btxmlc repair` to inspect conflicts. Run `btxmlc repair --write` to resolve the conflict interactively."},[e.DuplicateBehaviorTreeIdInWorkspace]:{code:e.DuplicateBehaviorTreeIdInWorkspace,title:"Duplicate BehaviorTree ID in workspace",description:"BehaviorTree IDs must be unique across the workspace.",suppressible:!1,invalidExample:`<!-- file1.xml --><BehaviorTree ID="shared"/>
+<!-- file2.xml --><BehaviorTree ID="shared"/>`,validExample:`<!-- file1.xml --><BehaviorTree ID="shared"/>
+<!-- file2.xml --><BehaviorTree ID="other"/>`,configExample:'{"linter":{"rules":{"tree/no-duplicate-id":"warn"}}}'},[e.MissingIncludePath]:{code:e.MissingIncludePath,title:"Missing include path",description:"include elements require a path attribute.",suppressible:!1,invalidExample:"<include/>",validExample:'<include path="common.xml"/>',configExample:'{"linter":{"rules":{"include/require-path":"warn"}}}'},[e.IncludeNotFound]:{code:e.IncludeNotFound,title:"Include not found",description:"Referenced include file does not exist.",suppressible:!1,invalidExample:'<include path="missing.xml"/>',validExample:'<include path="common.xml"/>',configExample:'{"linter":{"rules":{"include/no-missing-file":"warn"}}}'},[e.IncludeCycle]:n(e.IncludeCycle,"Include cycle","Include graph cycles are not allowed.",!1),[e.UnresolvedIncludePathVariable]:n(e.UnresolvedIncludePathVariable,"Unresolved include path variable","Include path variables must resolve before lookup.",!1),[e.IncludeOutsideWorkspace]:n(e.IncludeOutsideWorkspace,"Include outside workspace","Includes must stay within the workspace root.",!1),[e.ExternalIncludeUsed]:n(e.ExternalIncludeUsed,"External include used","An include file outside the workspace root was used.",!1),[e.IncludeDepthExceeded]:n(e.IncludeDepthExceeded,"Include depth exceeded","The maximum depth of nested includes was reached.",!1),[e.TooManyResolvedFiles]:n(e.TooManyResolvedFiles,"Too many resolved files","The maximum number of allowed files included was reached.",!1),[e.EntrypointNotFound]:n(e.EntrypointNotFound,"Entrypoint not found","Configured entrypoint files must exist.",!1),[e.RosPackageResolverMissing]:{code:e.RosPackageResolverMissing,title:"ROS package resolver is missing",description:"include elements with ros_pkg require ProjectHost.resolvePackageUri to be provided.",suppressible:!1,invalidExample:'<include ros_pkg="my_pkg" path="trees/common.xml"/>',validExample:"Provide a host implementation of resolvePackageUri that resolves my_pkg to a package root URI."},[e.RosPackageNotFound]:{code:e.RosPackageNotFound,title:"ROS package not found",description:"ros_pkg include must resolve to a known package root URI.",suppressible:!1,invalidExample:'<include ros_pkg="missing_pkg" path="trees/common.xml"/>',validExample:'<include ros_pkg="my_pkg" path="trees/common.xml"/>'},[e.UnknownNode]:n(e.UnknownNode,"Unknown node","Node usages must resolve to a known model.",!0),[e.MissingRequiredPort]:{code:e.MissingRequiredPort,title:"Missing required port",description:"Required ports must be supplied.",suppressible:!0,invalidExample:'<Action ID="SetFlag"/>',validExample:'<Action ID="SetFlag" enabled="true"/>',configExample:'{"linter":{"rules":{"model/require-port":"warn"}}}'},[e.UnknownPort]:{code:e.UnknownPort,title:"Unknown port",description:"Unknown ports are reported against the resolved node model.",suppressible:!0,invalidExample:'<Action ID="SetFlag" unknown="1"/>',validExample:'<Action ID="SetFlag" enabled="true"/>',configExample:'{"linter":{"rules":{"model/no-unknown-port":"error"}}}'},[e.InvalidPortValueType]:{code:e.InvalidPortValueType,title:"Invalid port value type",description:"Port values must match the declared type.",suppressible:!0,invalidExample:'<Action ID="SetFlag" enabled="yes"/>',validExample:'<Action ID="SetFlag" enabled="true"/>',configExample:'{"linter":{"rules":{"model/valid-port-value":"warn"}}}'},[e.BlackboardTypeMismatch]:{code:e.BlackboardTypeMismatch,title:"Blackboard type mismatch",description:"Blackboard entries must not mix incompatible resolved port types.",suppressible:!0,invalidExample:'<Sequence><ReadPose pose="{target}"/><UseString text="{target}"/></Sequence>',validExample:'<Sequence><ReadPose pose="{target}"/><UsePose pose="{target}"/></Sequence>',configExample:'{"linter":{"rules":{"model/no-blackboard-type-mismatch":["warn",{"allowStringEntryCompatibility":true}]}}}'},[e.CustomLiteralRequiresValidator]:{code:e.CustomLiteralRequiresValidator,title:"Custom literal requires validator",description:"Literal values for custom port types require a validator.",suppressible:!0,invalidExample:'<Action ID="MoveTo" target="1.0;2.0;3.14"/>',validExample:'<Action ID="MoveTo" target="{target}"/>',configExample:'{"linter":{"rules":{"model/valid-port-value":"warn"}}}'},[e.InvalidPortDefaultValue]:{code:e.InvalidPortDefaultValue,title:"Invalid port default value",description:"TreeNodesModel port defaults must match the declared type.",suppressible:!0,invalidExample:'<input_port name="count" type="int" default="abc"/>',validExample:'<input_port name="count" type="int" default="1"/>',configExample:'{"linter":{"rules":{"model/valid-port-default-value":"warn"}}}'},[e.OutputPortRequiresRemap]:{code:e.OutputPortRequiresRemap,title:"Output port requires remap",description:"Resolved output ports must write to a blackboard remap.",suppressible:!0,invalidExample:'<Action ID="Producer" result="value"/>',validExample:'<Action ID="Producer" result="{value}"/>',configExample:'{"linter":{"rules":{"model/require-output-port-remap":"error"}}}'},[e.AugmentTargetNotFound]:{code:e.AugmentTargetNotFound,title:"Augmentation target not found",description:"Model augmentations must target an existing node model.",suppressible:!1,invalidExample:'{"augment":{"MissingNode":{"ports":{}}}}',validExample:'{"augment":{"MoveTo":{"ports":{}}}}'},[e.AugmentPortNotFound]:{code:e.AugmentPortNotFound,title:"Augmentation port not found",description:"Model augmentations must target an existing port on the node model.",suppressible:!1,invalidExample:'{"augment":{"MoveTo":{"ports":{"missing":{}}}}}',validExample:'{"augment":{"MoveTo":{"ports":{"target":{}}}}}'},[e.InvalidTypeRefinement]:{code:e.InvalidTypeRefinement,title:"Invalid type refinement",description:"Model augmentation type refinements must match the port base type when `from` is provided.",suppressible:!1,invalidExample:'{"typeRefinement":{"from":"std::string","to":"Pose2D"}}',validExample:'{"typeRefinement":{"from":"int","to":"Pose2D"}}'},[e.ChildCapableNodeSelfClosing]:{code:e.ChildCapableNodeSelfClosing,title:"Child-capable node is self-closing",description:"Control and decorator nodes should normally use open/close tags.",suppressible:!0,invalidExample:"<Sequence/>",validExample:`<Sequence>
+  <AlwaysSuccess/>
+</Sequence>`,configExample:'{"linter":{"rules":{"model/no-childless-control-shape-mismatch":"off"}}}'},[e.LeafNodeOpenClose]:{code:e.LeafNodeOpenClose,title:"Leaf node uses block shape",description:"Leaf nodes should normally be self-closing unless they contain child nodes.",suppressible:!0,invalidExample:"<AlwaysSuccess></AlwaysSuccess>",validExample:"<AlwaysSuccess/>",configExample:'{"linter":{"rules":{"model/no-leaf-block-shape":"off"}}}'},[e.InvalidChildCount]:{code:e.InvalidChildCount,title:"Invalid child count",description:"Node child count must satisfy the constraints for its kind: Action/Condition have no children, Decorator has exactly one, Control has one or more, SubTree has none, and special builtins like IfThenElse/WhileDoElse require 2 or 3.",suppressible:!0,invalidExample:"<Sequence/>",validExample:"<Sequence><AlwaysSuccess/></Sequence>",configExample:'{"linter":{"rules":{"model/valid-child-count":"warn"}}}'},[e.ExternalModelFileNotFound]:{code:e.ExternalModelFileNotFound,title:"External model file not found",description:"Configured external TreeNodesModel files must exist.",suppressible:!1,invalidExample:'{"models":{"files":["missing.xml"]}}',validExample:'{"models":{"files":["models.xml"]}}'},[e.AugmentationFileNotFound]:{code:e.AugmentationFileNotFound,title:"Augmentation file not found",description:"Configured augmentation files must exist.",suppressible:!1,invalidExample:'{"models":{"augmentations":["missing.xml"]}}',validExample:'{"models":{"augmentations":["augmentations.xml"]}}'},[e.MissingTreeNodesModel]:n(e.MissingTreeNodesModel,"Missing TreeNodesModel","External model files must contain a TreeNodesModel.",!1),[e.ExternalModelXmlParseError]:n(e.ExternalModelXmlParseError,"External model XML parse error","External model files must parse as XML.",!1),[e.NodeDefinitionFileNotFound]:{code:e.NodeDefinitionFileNotFound,title:"Node definition file not found",description:"Configured node definition files must exist.",suppressible:!1,invalidExample:'{"models":{"definitions":["missing.json"]}}',validExample:'{"models":{"definitions":["nodes.json"]}}'},[e.InvalidNodeDefinitionJson]:n(e.InvalidNodeDefinitionJson,"Invalid node definition JSON","Node definition files must parse as JSON.",!1),[e.InvalidNodeDefinitionSchema]:n(e.InvalidNodeDefinitionSchema,"Invalid node definition schema","Node definition files must match the expected schema.",!1),[e.DuplicateNodeDefinitionId]:n(e.DuplicateNodeDefinitionId,"Duplicate node definition ID","Node definition IDs must be unique.",!1),[e.InvalidAugmentationJson]:n(e.InvalidAugmentationJson,"Invalid augmentation JSON","Model augmentation files must parse as JSON.",!1),[e.InvalidAugmentationSchema]:n(e.InvalidAugmentationSchema,"Invalid augmentation schema","Model augmentation files must match the expected schema.",!1),[e.ConflictingPortDefault]:{code:e.ConflictingPortDefault,title:"Conflicting port default",description:"Merged port defaults must agree.",suppressible:!1,fix:"Run `btxmlc repair` to inspect conflicts. Run `btxmlc repair --write` to resolve the conflict interactively."},[e.UnusedSuppression]:n(e.UnusedSuppression,"Unused suppression","Suppressions should match at least one diagnostic.",!1),[e.MissingSuppressionReason]:n(e.MissingSuppressionReason,"Missing suppression reason","Suppressions should include a reason when required.",!1),XML016_TEXT_OUTSIDE_ROOT:n("XML016_TEXT_OUTSIDE_ROOT","Text outside root element","Non-whitespace text is not allowed outside the root element.",!1)},L=Object.fromEntries(Object.values(s).flatMap(t=>{let o=t;return[o.code,...(o.codes??[]).filter(i=>i!==o.code)].map(i=>[i,o.defaultSeverity])})),F={[e.DuplicateNodeModelId]:"error",[e.UnknownTopLevelElement]:"warning",[e.UnresolvedIncludePathVariable]:"error",[e.ExternalIncludeUsed]:"info",[e.IncludeDepthExceeded]:"error",[e.TooManyResolvedFiles]:"error",[e.EntrypointNotFound]:"error",[e.ExternalModelFileNotFound]:"error",[e.AugmentationFileNotFound]:"error",[e.MissingTreeNodesModel]:"error",[e.ExternalModelXmlParseError]:"error",[e.NodeDefinitionFileNotFound]:"error",[e.InvalidNodeDefinitionJson]:"error",[e.InvalidNodeDefinitionSchema]:"error",[e.DuplicateNodeDefinitionId]:"error",[e.InvalidAugmentationJson]:"error",[e.InvalidAugmentationSchema]:"error",[e.CustomLiteralRequiresValidator]:"error",[e.InvalidPortDefaultValue]:"error",[e.InvalidPortName]:"error",[e.AugmentTargetNotFound]:"error",[e.AugmentPortNotFound]:"error",[e.InvalidTypeRefinement]:"error",[e.ConflictingPortDefault]:"warning",[e.EmptyScript]:"error",[e.InvalidScriptToken]:"error",[e.InvalidCompoundAssignment]:"error",[e.ScriptVariableTypeMismatch]:"error",XML016_TEXT_OUTSIDE_ROOT:"error"};function V(t){let o=L[t]??F[t];if(!o)throw new Error(`Missing default severity metadata for ${t}`);return o}var c={};for(let[t,o]of Object.entries(U))c[t]={...o,defaultSeverity:V(t)};var S={};for(let[t,o]of Object.entries(s)){let i=c[o.code];if(i){let r=o;S[t]=r.options?{...i,options:r.options}:i}}function C(t){return c[t]}function w(t){return S[t]??c[t]}function O(){return[...Object.values(e)].sort()}function R(){return Object.keys(s).sort()}function M(){let t=[];for(let o of R()){let i=S[o];i&&t.push({name:o,metadata:i})}return t}export{s as RULES,T as RULE_CODES,e as RuleCodes,C as findRuleMetadata,x as getDiagnosticCodeForRule,I as getNodeUsagePolicyForRules,w as getRuleMetadata,_ as getRuleNameForCode,h as getRuleSeverity,v as isRuleName,O as listRuleCodes,R as listRuleSlugs,M as listRules,u as normalizeRuleConfig,b as validateRawConfigRules,y as validateRuleOptions};

package/dist/semantic.d.ts

@@ -0,0 +1,42 @@
+import { B as BtDocument, a as BtXmlElement } from './ast-BbfR3S_b.js';
+import { a as SemanticIndexOptions, b as SemanticIndexResult, S as SemanticIndex, c as ModelConflictFact } from './types-BaOc_AYN.js';
+import { B as BuildSemanticDocumentViewOptions, S as SemanticDocumentView, a as SemanticTreeNodeView, b as SemanticPortBindingView, c as SemanticSubTreeCallView } from './types-CkOvIGPf.js';
+import { c as SourcePosition } from './diagnostic-B5htzyJ9.js';
+import { P as PortDef, a as TreeNodeModelDef, S as SubTreeReference, B as BehaviorTreeDef } from './public-types-B2noBQY9.js';
+import { R as ResolveNodeUsageInput, b as ResolvePortUsageInput, P as PortUsageResolution, N as NodeUsageResolution } from './types-SY4-jKCn.js';
+export { a as NodeUsagePolicy, S as SubTreeResolution, r as resolveSubTreeTarget } from './types-SY4-jKCn.js';
+import './types-BgqDzlJ8.js';
+import 'zod';
+
+declare function buildSemanticIndex(documents: BtDocument[], options: SemanticIndexOptions): SemanticIndexResult;
+
+declare const GENERIC_NODE_TAGS: readonly ["Action", "Condition", "Control", "Decorator"];
+type GenericNodeKind = (typeof GENERIC_NODE_TAGS)[number];
+declare function isGenericNodeTag(name: string): name is GenericNodeKind;
+declare function getGenericNodeKindFromTag(name: string): GenericNodeKind | undefined;
+declare function getNodeTypeFromElement(element: BtXmlElement): string | undefined;
+
+declare function resolvePortUsage(index: SemanticIndex, input: ResolvePortUsageInput): PortUsageResolution | undefined;
+declare function getUsagePorts(index: SemanticIndex, input: ResolveNodeUsageInput): readonly PortDef[];
+
+declare function resolveNodeUsage(index: SemanticIndex, input: ResolveNodeUsageInput): NodeUsageResolution;
+
+declare function buildSemanticDocumentView(document: BtDocument, index: SemanticIndex, options?: BuildSemanticDocumentViewOptions): SemanticDocumentView;
+
+declare function getAllSemanticTreeNodes(view: SemanticDocumentView): readonly SemanticTreeNodeView[];
+declare function getSemanticSubTreeCalls(view: SemanticDocumentView): readonly SemanticSubTreeCallView[];
+declare function findSemanticNodeAtPosition(view: SemanticDocumentView, position: SourcePosition): SemanticTreeNodeView | undefined;
+declare function findSemanticPortBindingAtPosition(view: SemanticDocumentView, position: SourcePosition): SemanticPortBindingView | undefined;
+
+declare function getBehaviorTrees(index: SemanticIndex, id: string): BehaviorTreeDef[];
+declare function getSubTreeReferences(index: SemanticIndex, id: string): SubTreeReference[];
+declare function getAllSubTreeReferences(index: SemanticIndex): SubTreeReference[];
+declare function getBehaviorTreeIds(index: SemanticIndex): string[];
+declare function getNodeModel(index: SemanticIndex, id: string): TreeNodeModelDef | undefined;
+declare function getNodeModelDefinitions(index: SemanticIndex, id: string): TreeNodeModelDef[];
+declare function getAllNodeModels(index: SemanticIndex): TreeNodeModelDef[];
+declare function getEffectiveNodeModels(index: SemanticIndex): TreeNodeModelDef[];
+declare function getGenericSubTreePorts(index: SemanticIndex): readonly PortDef[];
+declare function getModelConflicts(index: SemanticIndex): ModelConflictFact[];
+
+export { type GenericNodeKind, NodeUsageResolution, PortUsageResolution, ResolveNodeUsageInput, ResolvePortUsageInput, SemanticDocumentView, SemanticIndex, SemanticIndexOptions, SemanticIndexResult, SemanticPortBindingView, SemanticTreeNodeView, buildSemanticDocumentView, buildSemanticIndex, findSemanticNodeAtPosition, findSemanticPortBindingAtPosition, getAllNodeModels, getAllSemanticTreeNodes, getAllSubTreeReferences, getBehaviorTreeIds, getBehaviorTrees, getEffectiveNodeModels, getGenericNodeKindFromTag, getGenericSubTreePorts, getModelConflicts, getNodeModel, getNodeModelDefinitions, getNodeTypeFromElement, getSemanticSubTreeCalls, getSubTreeReferences, getUsagePorts, isGenericNodeTag, resolveNodeUsage, resolvePortUsage };