@abco20/btxml-checker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 btxml contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# btxml-checker
+
+BehaviorTree.CPP XML checker and formatter.
+
+## Installation
+
+Install in a project:
+
+```bash
+npm install --save-dev @abco20/btxml-checker
+npx btxmlc check "behavior_trees/**/*.xml"
+```
+
+Use once without installing first:
+
+```bash
+npx @abco20/btxml-checker check "behavior_trees/**/*.xml"
+```
+
+## CLI Usage
+
+Commands:
+
+- `btxmlc format` rewrites XML into Groot-compatible layout.
+- `btxmlc format --check` only reports whether formatting differs.
+- `btxmlc lint` checks XML syntax and BT rules.
+- `btxmlc lint --fix` applies safe, deterministic lint fixes.
+- `btxmlc check` runs format check and lint together.
+- `btxmlc repair` interactively resolves conflicting node model definitions.
+- `btxmlc init` creates a starter `btxml.config.json`.
+- `btxmlc explain <code>` shows documentation for a rule code.
+- `btxmlc doctor` diagnoses workspace health.
+
+By default, `btxmlc format` formats only BehaviorTree.CPP XML files. Generic XML files such as `package.xml` are skipped unless `--force` is specified.
+
+Use `lint --fix` for safe automatic fixes:
+
+```bash
+npx btxmlc lint --fix
+```
+
+Use `repair` for node model conflicts that require a choice:
+
+```bash
+npx btxmlc repair
+npx btxmlc repair --write
+```
+
+`btxmlc check` and `btxmlc lint` support `--output human` and `--output json`.
+
+```bash
+npx btxmlc check --output json
+npx btxmlc lint --output json
+```
+
+## Configuration
+
+Place `btxml.config.json` in the root of your project.
+
+Minimal config:
+
+```json
+{
+  "$schema": "./node_modules/@abco20/btxml-checker/schemas/btxml.config.schema.json"
+}
+```
+
+Common project config:
+
+```json
+{
+  "$schema": "./node_modules/@abco20/btxml-checker/schemas/btxml.config.schema.json",
+  "files": {
+    "include": ["behavior_trees/**/*.xml"]
+  },
+  "resolver": {
+    "entrypoints": ["behavior_trees/main.xml"]
+  },
+  "models": {
+    "files": ["behavior_trees/models/**/*.xml"],
+    "definitions": ["behavior_trees/nodes.json"]
+  },
+  "linter": {
+    "rules": {
+      "model/no-unknown-port": "error"
+    }
+  },
+  "formatter": {
+    "indentWidth": 2,
+    "xmlDeclaration": "always",
+    "blankLineBetweenBehaviorTrees": true,
+    "lineEnding": "lf"
+  }
+}
+```
+
+Disable bundled BT.CPP built-in node models if your project provides its own definitions:
+
+```json
+{
+  "models": {
+    "builtins": []
+  }
+}
+```
+
+## TypeScript API
+
+Use the public package exports only:
+
+```ts
+import { checkBtWorkspace, formatBtXml, normalizeBtxmlConfig } from "@abco20/btxml-checker";
+import { createBtEditorService, type BtEditorService } from "@abco20/btxml-checker/editor";
+import { getNodeTypeFromElement, isGenericNodeTag } from "@abco20/btxml-checker/semantic";
+
+const { config, ok, diagnostics } = normalizeBtxmlConfig({
+  strict: true,
+});
+
+if (!ok) {
+  throw new Error(diagnostics.map((diag) => diag.message).join("\n"));
+}
+
+const result = await checkBtWorkspace(
+  {
+    inputs: [
+      {
+        uri: "file:///workspace/behavior_trees/main.xml",
+        path: "behavior_trees/main.xml",
+        kind: "bt-xml",
+        text: `<?xml version="1.0"?>\n<root BTCPP_format="4"><BehaviorTree ID="Main"/></root>`,
+      },
+    ],
+    config,
+  },
+);
+
+console.log(result.ok, result.summary.errors);
+
+const service: BtEditorService = createBtEditorService();
+service.openDocument("memory:///tree.xml", `<root BTCPP_format="4"><BehaviorTree ID="Main"/></root>`);
+
+const semantic = service.getSemanticDocumentView("memory:///tree.xml");
+const firstNode = semantic.view?.nodes[0];
+if (firstNode) {
+  console.log(getNodeTypeFromElement(firstNode.usage.element));
+  console.log(isGenericNodeTag(firstNode.tagName));
+}
+
+console.log(formatBtXml(`<root BTCPP_format="4"><BehaviorTree ID="Main"/></root>`));
+```
+
+Avoid importing internal modules or internal-only types such as parser internals, semantic indexes, or project index structures.
+
+## Limitations
+
+CDATA, DOCTYPE, non-declaration processing instructions, and unknown XML entities are unsupported in v0.1.
+
+See the repository README and docs for the full configuration and rule reference.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third Party Notices
+
+This package includes data derived from BehaviorTree.CPP built-in node model definitions through `@btxml/model`.
+
+## BehaviorTree.CPP
+
+Repository: https://github.com/BehaviorTree/BehaviorTree.CPP
+
+License: MIT
+
+```text
+MIT License
+
+Copyright (c) 2018-2024 Davide Faconti and BehaviorTree.CPP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/ast-BbfR3S_b.d.ts

@@ -0,0 +1,62 @@
+import { S as SourceRange, D as Diagnostic } from './diagnostic-B5htzyJ9.js';
+
+type XmlDeclaration = {
+    version?: string;
+    encoding?: string;
+    standalone?: string;
+    range: SourceRange;
+    attributes?: BtXmlAttribute[];
+};
+type BtXmlText = {
+    kind: "text";
+    text: string;
+    range: SourceRange;
+    fullRange?: SourceRange;
+};
+type BtXmlComment = {
+    kind: "comment";
+    text: string;
+    range: SourceRange;
+    fullRange?: SourceRange;
+    contentRange?: SourceRange;
+};
+type BtXmlAttribute = {
+    name: string;
+    value: string;
+    valueOffsets?: readonly number[];
+    range: SourceRange;
+    fullRange?: SourceRange;
+    nameRange: SourceRange;
+    equalsRange?: SourceRange;
+    valueRange: SourceRange;
+    valueContentRange?: SourceRange;
+};
+type BtXmlElement = {
+    kind: "element";
+    name: string;
+    attributes: BtXmlAttribute[];
+    children: BtXmlNode[];
+    range: SourceRange;
+    fullRange?: SourceRange;
+    openTagRange: SourceRange;
+    startTagRange?: SourceRange;
+    closeTagRange?: SourceRange;
+    endTagRange?: SourceRange;
+    nameRange?: SourceRange;
+    selfClosing: boolean;
+};
+type BtXmlNode = BtXmlElement | BtXmlText | BtXmlComment;
+type BtDocumentKind = "bt-document" | "model-document" | "generic-xml" | "invalid-xml";
+type BtDocument = {
+    uri: string;
+    path?: string;
+    kind: BtDocumentKind;
+    isBtXml: boolean;
+    xmlDeclaration?: XmlDeclaration;
+    root?: BtXmlElement;
+    nodes: BtXmlNode[];
+    diagnostics: Diagnostic[];
+    originalText: string;
+};
+
+export type { BtDocument as B, XmlDeclaration as X, BtXmlElement as a, BtXmlAttribute as b, BtXmlNode as c, BtDocumentKind as d, BtXmlComment as e, BtXmlText as f };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node