{ "markdown": "

\n \"Rulemorph\"\n

\n\n

\n \"Crates.io\"\n \"docs.rs\"\n \"License:\n

\n\nRulemorph transforms data from external APIs, CSV, JSON, YAML, TOML, XML, HTML, Markdown, and Excel into predictable JSON using declarative YAML/JSON rules.\n\nInstead of adding another custom script for every input source, you can keep transformation behavior in rule files. The same rules can be reused from the CLI, embedded in Rust, served through a local UI/API server, or exposed to AI assistants through MCP.\n\nTry it in your browser: [playground.rulemorph.com](https://playground.rulemorph.com/)\n\n## What It Solves\n\nRulemorph moves growing transformation code into reviewable, versioned rules.\n\n- Normalize vendor API responses into your internal schema\n- Bring CSV / Excel imports into a JSON pipeline\n- Extract values from HTML or XML and process them with the same rule model\n- Review, replace, and version transformation behavior as YAML/JSON\n- Reuse the same transformation from the CLI, a local API, or an AI assistant\n\nIt is not meant to replace application code for arbitrary execution, complex domain logic, or long-running workflow orchestration. For those cases, normal application code or a workflow engine is usually a better fit.\n\n## Quick Start\n\nTransform a `users` array from an external API response into the JSON shape your application expects.\n\n**rules.yaml**\n\n```yaml\nversion: 2\ninput:\n format: json\n json:\n records_path: \"users\"\nmappings:\n - target: \"id\"\n source: \"user_id\"\n - target: \"name\"\n expr: [\"@input.full_name\", trim]\n - target: \"email\"\n expr: [\"@input.username\", concat: [\"lit:@example.com\"]]\n```\n\n**input.json**\n\n```json\n{ \"users\": [{ \"user_id\": 1, \"full_name\": \" Alice \", \"username\": \"alice\" }] }\n```\n\n**Run**\n\n```sh\nrulemorph transform -r rules.yaml -i input.json\n```\n\nYou can also pipe input to `transform`:\n\n```sh\ncat input.json | rulemorph transform -r rules.yaml\ncat input.json | rulemorph transform -r rules.yaml -i -\n```\n\n**Output**\n\n
\nShow output\n\n```json\n[{ \"id\": 1, \"name\": \"Alice\", \"email\": \"alice@example.com\" }]\n```\n\n
\n\nFor quick one-off transformations without a rule file, use direct mode.\n\nEvaluate a single expression against JSON or ad-hoc CSV:\n\n```sh\necho '{ \"test\": 1 }' | rulemorph -rule '@input.test'\necho '{ \"a\": 1, \"b\": 2 }' | rulemorph --rule '[\"@input.a\", {\"+\": [\"@input.b\"]}]'\necho 'a,test,1' | rulemorph -rule '@input.0'\necho 'a,test,1' | rulemorph -H 'id,name,age' -rule '@input.id'\n```\n\n
\nShow output\n\n```text\n1\n3\n\"a\"\n\"a\"\n```\n\n
\n\nUse `-F/--field` when you want a small output object and field order matters:\n\n```sh\necho 'u1,Alice,42' | rulemorph -H 'id,name,age' \\\n -F id='@input.id' \\\n -F name='[\"@input.name\",\"trim\",\"uppercase\"]' \\\n -F age='[\"@input.age\",\"int\"]'\n```\n\n
\nShow output\n\n```json\n{ \"id\": \"u1\", \"name\": \"ALICE\", \"age\": 42 }\n```\n\n
\n\nUse `--output-map` when a compact nested target map is easier to read:\n\n```sh\necho 'u1,Alice,42' | rulemorph -H 'id,name,age' \\\n --output-map '{\"user.id\":\"@input.id\",\"user.name\":[\"@input.name\",\"trim\"],\"age\":[\"@input.age\",\"int\"]}'\n```\n\n
\nShow output\n\n```json\n{ \"user\": { \"id\": \"u1\", \"name\": \"Alice\" }, \"age\": 42 }\n```\n\n
\n\nFor multi-record direct input, add `--ndjson` to emit one JSON value per line:\n\n```sh\nprintf 'u1,Alice,42\\nu2,Bob,7\\n' | rulemorph --ndjson -H 'id,name,age' \\\n --output-map '{\"id\":\"@input.id\",\"age\":[\"@input.age\",\"int\"]}'\n```\n\n
\nShow output\n\n```jsonl\n{\"age\":42,\"id\":\"u1\"}\n{\"age\":7,\"id\":\"u2\"}\n```\n\n
\n\nDirect mode can also read CSV or Excel files. CSV headers are inferred from `.csv`\nfiles; use `-H/--headers` for headerless CSV. For Excel, select the header row\nand data range explicitly:\n\n```sh\nrulemorph --rule '@input.id' -i users.csv\nrulemorph -H 'id,name,age' --rule '@input.id' -i headerless-users.csv\nrulemorph --rule '@input.id' -i users.xlsx --excel-header-row 1 --excel-data-range A2:D20\n```\n\n
\nShow output\n\n```text\n\"u1\"\n\"u1\"\n[\"u1\",\"u2\"]\n```\n\n
\n\n

\n \"Rulemorph\n

\n\n\n## Which Package To Use\n\n| Goal | Use |\n| --- | --- |\n| Try rules without installing anything | [Rulemorph Playground](https://playground.rulemorph.com/) |\n| File transforms, DTO generation, CI validation | `rulemorph` CLI |\n| Embed transformations in a Rust application | `rulemorph` crate |\n| Run the local UI or YAML-defined APIs | `rulemorph-server` |\n| Use transforms, validation, and DTO generation from an AI assistant | `rulemorph-mcp` |\n\n## Installation\n\nPrebuilt binaries for the CLI, server, and MCP server are available from [GitHub Releases](https://github.com/vinhphatfsg/rulemorph/releases).\n\n### CLI\n\n```sh\nbrew install vinhphatfsg/tap/rulemorph\n```\n\nBuild from source for development:\n\n```sh\ncargo build -p rulemorph_cli --release\n./target/release/rulemorph --help\n```\n\n### UI / API Server\n\n```sh\nbrew install vinhphatfsg/tap/rulemorph-server\nrulemorph-server --rules-dir ./api_rules --api-mode rules\n```\n\nFor full startup steps, see the [UI Server Guide](docs/guide/ui-run-and-verify-en.md).\n\n### MCP Server\n\n`rulemorph-mcp` exposes Rulemorph capabilities to AI assistants through the Model Context Protocol.\n\n- `transform`: transform data\n- `validate_rules`: validate rules\n- `generate_dto`: generate DTOs\n- `analyze_input`: summarize input structure\n\nClaude Code setup:\n\n```sh\nclaude mcp add rulemorph -- rulemorph-mcp\n```\n\n## Key Features\n\n- Normalize CSV / JSON / YAML / TOML / XML / HTML / Markdown / `.xlsx` Excel into JSON records\n- Build output fields with `mappings`\n- Transform values with v2 pipe expressions: trim, case conversion, concatenation, numeric operations, lookups, and array operations\n- Define rule-local custom OPs with `defs` to reuse typed v2 pipes or mapping bodies\n- Use numeric helpers such as `sqrt`, `mod`, `pow`, `clamp`, and `range` for bounded generated sequences\n- Control behavior with `record_when`, `when`, and `asserts`\n- Use `steps`, `branch`, and `finalize` for ordered execution and output-array processing\n- Generate inferred DTOs for Rust, TypeScript, Python, Go, Java, Kotlin, and Swift. Explicit `type` wins; dynamic or unsafe shapes fall back to JSON-friendly types.\n- Inspect semantic traces for built-in and custom OP execution without changing transform output\n- Run a local UI/API server or expose the same engine through MCP\n\nInput parsers are designed to be conservative. HTML parsing does not execute JavaScript or fetch URLs, Markdown raw HTML is preserved only as source text, and Excel parsing does not execute macros or evaluate formulas. XML DTD/entities and JSON/YAML duplicate keys are rejected to avoid ambiguous or side-effectful input behavior.\n\n## Rule Structure\n\n```yaml\nversion: 2\ninput:\n format: json # csv | json | yaml | toml | xml | html | markdown | excel\n json:\n records_path: \"items\"\nmappings:\n - target: \"output.field\"\n source: \"input.field\"\n type: string\n when:\n eq: [\"@input.status\", \"active\"]\n```\n\nNew rule files should use `version: 2`. `version: 1` rule files are still accepted during migration, but validation and runtime entry points emit a deprecation warning. A later release will move `version: 1` rule files behind an explicit legacy opt-in before removing that syntax.\n\nFor the full rule specification, see [Transformation Rules Spec](docs/rules_spec_en.md). The Japanese version is also available in [Japanese](docs/rules_spec_ja.md).\n\n## DTO Generation\n\n```sh\nrulemorph generate -r rules.yaml -l typescript\n```\n\n```typescript\nexport interface Record {\n id: number;\n name: string;\n email: string;\n}\n```\n\nSupported languages: `rust`, `typescript`, `python`, `go`, `java`, `kotlin`, `swift`\n\nDTO generation uses explicit mapping types first, then infers simple scalar, array, map, and nested object shapes from literals and v2 pipe expressions. If a shape is dynamic or too broad to infer safely, the generated DTO uses each language's JSON fallback type.\n\n## Library Usage\n\n```toml\n[dependencies]\nrulemorph = \"0.3.4\"\n```\n\nThe `html`, `excel`, and `markdown` input parsers are enabled by default. Library users that only need\ncore CSV, JSON, YAML, TOML, and XML support can disable them to reduce optional parser dependencies:\n\n```toml\n[dependencies]\nrulemorph = { version = \"0.3.4\", default-features = false }\n```\n\nRe-enable parsers explicitly with features such as `[\"html\"]`, `[\"excel\"]`, or `[\"markdown\"]`.\nIf a disabled parser is selected by a rule, transformation fails with `invalid_input` (for Markdown: `input format markdown is not enabled in this build`).\n\n```rust\nuse rulemorph::{parse_rule_file, transform};\n\nlet rule = parse_rule_file(&std::fs::read_to_string(\"rules.yaml\")?)?;\nlet input = std::fs::read_to_string(\"input.json\")?;\nlet output = transform(&rule, &input, None)?;\n```\n\n## Documentation\n\n- [Documentation index](docs/README.md)\n- [Transformation Rules Spec](docs/rules_spec_en.md) / [Japanese](docs/rules_spec_ja.md)\n- [Endpoint Rules Spec](docs/rules_spec_endpoint_ja.md)\n- [Network Rules Spec](docs/rules_spec_network_ja.md)\n- [UI Server Guide](docs/guide/ui-run-and-verify-en.md) / [Japanese](docs/guide/ui-run-and-verify.md)\n- [UI Data Directory](docs/guide/ui-data-dir-usage-en.md) / [Japanese](docs/guide/ui-data-dir-usage.md)\n", "bytes": 9755, "sha": "024cb603488b2993980394d18bf0253fe5651aea28809b4264507a655b107cd0", "repo_slug": "vinhphatfsg/transform-rules-rs", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_vinhphatfsg_transform_rules_mc_869586e8/readme" }