jsmn-tools 0.1.0__tar.gz

jsmn_tools-0.1.0/.clang-format

@@ -0,0 +1,14 @@
+BasedOnStyle: LLVM
+ColumnLimit: 80
+# Return type on its own line, brace on new line for functions
+BreakAfterReturnType: All
+BreakBeforeBraces: Linux
+BinPackParameters: false
+BinPackArguments: false
+AllowAllParametersOfDeclarationOnNextLine: false
+InsertBraces: true
+IndentWidth: 4
+AlignConsecutiveDeclarations:
+  Enabled: true
+  AcrossEmptyLines: false
+  AcrossComments: true

jsmn_tools-0.1.0/.clangd

@@ -0,0 +1,2 @@
+CompileFlags:
+  CompilationDatabase: build/

jsmn_tools-0.1.0/.cmake-format.yaml

@@ -0,0 +1,16 @@
+line_width: 100
+tab_size: 4
+enable_markup: false
+max_subgroups_hwrap: 3
+max_pargs_hwrap: 6
+separate_ctrl_name_with_space: false
+separate_fn_name_with_space: false
+dangle_parens: true
+dangle_align: prefix
+min_prefix_chars: 4
+max_prefix_chars: 10
+max_lines_hwrap: 2
+command_case: canonical
+keyword_case: upper
+enable_sort: true
+autosort: true

jsmn_tools-0.1.0/.coveragerc

@@ -0,0 +1,7 @@
+[run]
+source = jsmn_tools
+
+[report]
+omit =
+    codegen/src/jsmn_tools/__main__.py
+    codegen/src/jsmn_tools/cli.py

jsmn_tools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    name: Tests & Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync
+
+      - name: Pytest with coverage
+        run: uv run pytest --cov=jsmn_tools --cov-report=term-missing --cov-fail-under=90
+
+      - name: Radon complexity
+        run: |
+          output=$(uv run radon cc codegen/src/jsmn_tools -n D --no-assert)
+          if echo "$output" | grep -qE "^\s+[FMCD]"; then
+            echo "::error::Complexity check failed — blocks rated D or worse:"
+            echo "$output"
+            exit 1
+          fi
+          echo "Radon check passed (threshold: D)"
+
+  e2e:
+    name: E2E (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: ilammy/msvc-dev-cmd@v1
+        if: runner.os == 'Windows'
+      - run: uv sync
+
+      - name: Configure
+        run: uv run cmake -B build -S codegen/tests/e2e -G Ninja
+
+      - name: Build
+        run: cmake --build build
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure

jsmn_tools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

jsmn_tools-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Dependencies
+node_modules/
+
+# Build outputs - TypeScript
+dist/
+*.tsbuildinfo
+
+# Build outputs - Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+eggs/
+*.egg-info/
+*.egg
+.installed.cfg
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Build outputs - CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+compile_commands.json
+Makefile
+!**/CMakeLists.txt
+.cache
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing / Coverage
+coverage/
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Sphinx
+docs/_build/
+
+# Claude
+.claude/
+
+# AI local artifacts (conversations, drafts with PII)
+docs/ai/local/

jsmn_tools-0.1.0/.importlinter

@@ -0,0 +1,10 @@
+[importlinter]
+root_package = jsmn_tools
+
+[importlinter:contract:layers]
+name = node <- walk <- spec layering
+type = layers
+layers =
+    jsmn_tools.spec
+    jsmn_tools.walk
+    jsmn_tools.node

jsmn_tools-0.1.0/.mypy.ini

@@ -0,0 +1,16 @@
+[mypy]
+python_version = 3.12
+files = codegen/src, codegen/tests
+exclude = codegen/tests/e2e
+strict = True
+warn_return_any = True
+warn_unused_ignores = True
+disallow_untyped_defs = True
+disallow_incomplete_defs = True
+check_untyped_defs = True
+no_implicit_optional = True
+warn_redundant_casts = True
+warn_unused_configs = True
+show_error_codes = True
+disallow_any_generics = False
+warn_unreachable = True

jsmn_tools-0.1.0/.prettierrc.yaml

@@ -0,0 +1,8 @@
+proseWrap: always
+printWidth: 80
+tabWidth: 2
+useTabs: false
+semi: true
+singleQuote: false
+trailingComma: es5
+bracketSpacing: true

jsmn_tools-0.1.0/CLAUDE.md

@@ -0,0 +1,47 @@
+# Jsmn Tools
+
+## Intro
+
+jsmn-tools is a code generation project. jsmn-tools generates code by
+crawling OpenAPI specifications and AsyncAPI specifications for "JSON Schemas".
+Code generation must be explicitly declared via OpenAPI and AsyncAPI extension.
+
+More details are in the design document. You should only need to consult the
+design document when you are assigned a task.
+
+## Design Pushback
+
+If you identify a design flaw in what I'm asking for, stop and flag it before
+implementing. Explain the concern and propose an alternative. Don't implement
+something you know is wrong just because I asked for it.
+
+Specific things to watch for:
+- Adding indirection (wrappers, abstractions, registries) without a concrete
+  second consumer
+- Premature generalization — solving hypothetical future requirements instead of
+  the actual task
+- Layering workarounds on top of a bad foundation instead of fixing the
+  foundation
+- Duplicating logic that should be factored, or factoring logic that only has
+  one call site
+
+When in doubt, push back with a short explanation and an alternative. I'd rather
+have a 30-second conversation than undo a bad design later.
+
+## Code Structure
+
+```
+codegen/
+  src/jsmn_tools/
+    cli.py          # CLI entry point
+    bundle.py       # Bundle logic for code generation
+    node/           # Node types, behaviors, locations, refs
+    spec/           # Spec structure definitions (OpenAPI 3.1, JSON Schema)
+    walk/           # Tree operations (walk, normalize, diff, merge, join)
+    lang/jsmn/      # C code generation (IR types, flatten, templates, runtime)
+  tests/
+    fixtures/       # Test fixtures (specs, templates)
+    unit/           # Unit tests
+    integration/    # Integration tests
+    e2e/            # Full end to end C integration test (via CMake)
+```

jsmn_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Altronix
+
+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.

jsmn_tools-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: jsmn-tools
+Version: 0.1.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: referencing>=0.35
+Requires-Dist: ruamel-yaml>=0.19.1

jsmn_tools-0.1.0/README.md

@@ -0,0 +1,43 @@
+# jsmn-tools
+
+[![CI](https://github.com/TomzBench/jsmn-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/TomzBench/jsmn-tools/actions/workflows/ci.yml)
+
+A code generator for JSON parsing in C.
+
+## Testing
+
+```bash
+uv run pytest                        # unit + integration
+uv run pytest --cov=jsmn_tools     # with coverage
+uv run pytest codegen/tests/unit     # unit only
+uv run radon cc codegen/src -a -nb   # cyclomatic complexity
+uv run radon mi codegen/src -nb      # maintainability index
+```
+
+# Building the docs
+
+## Prerequisites
+
+- Python >= 3.11
+- [uv](https://docs.astral.sh/uv/)
+
+## Setup
+
+```bash
+uv venv
+uv sync --extra docs
+```
+
+## Build
+
+```bash
+uv run sphinx-build -b html docs docs/_build
+```
+
+## Preview
+
+```bash
+uv run python -m http.server 8000 --directory docs/_build
+```
+
+Open [http://localhost:8000](http://localhost:8000).

jsmn_tools-0.1.0/cmake/modules/FindUnity.cmake

@@ -0,0 +1,47 @@
+# FindUnity.cmake
+#
+# Find or fetch the ThrowTheSwitch Unity test framework.
+#
+# First attempts find_package in CONFIG mode (for system-installed Unity).
+# Falls back to FetchContent from GitHub if not found.
+#
+# Options:
+#   UNITY_VERSION       - Git tag to fetch (default: v2.6.1)
+#   UNITY_FIND_REQUIRED - If TRUE, failure is fatal (standard find_package behavior)
+#
+# Imported targets:
+#   unity::framework   - The target to link against
+
+if(TARGET unity::framework)
+    return()
+endif()
+
+# Try system-installed Unity first (exports unity::framework)
+find_package(unity CONFIG QUIET)
+if(unity_FOUND)
+    set(Unity_FOUND TRUE)
+    return()
+endif()
+
+# Fall back to FetchContent
+include(FetchContent)
+
+if(NOT DEFINED UNITY_VERSION)
+    set(UNITY_VERSION "v2.6.1")
+endif()
+
+FetchContent_Declare(
+    unity
+    GIT_REPOSITORY https://github.com/ThrowTheSwitch/Unity.git
+    GIT_TAG ${UNITY_VERSION}
+    GIT_SHALLOW TRUE
+)
+
+FetchContent_MakeAvailable(unity)
+
+# Suppress MSVC Spectre mitigation warnings (C5045) on Unity sources
+if(MSVC AND TARGET unity)
+    target_compile_options(unity PRIVATE /wd5045)
+endif()
+
+set(Unity_FOUND TRUE)

jsmn_tools-0.1.0/cmake/modules/JsmnToolsConfig.cmake

@@ -0,0 +1,45 @@
+set(JsmnTools_FOUND TRUE)
+set(JsmnTools_VERSION "0.1.0")
+find_program(JsmnTools_EXECUTABLE jsmn-tools-codegen REQUIRED)
+
+macro(_append_if cond var)
+    if(${cond})
+        list(APPEND ${var} ${ARGN})
+    endif()
+endmacro()
+
+function(jsmn_tools_generate)
+    cmake_parse_arguments(ARG "" "TARGET;PREFIX" "SPECS;TEMPLATES;ENV" ${ARGN})
+
+    # Build --template pairs and collect outputs
+    list(LENGTH ARG_TEMPLATES templates_len)
+    math(EXPR templates_end "${templates_len} - 1")
+    foreach(i RANGE 0 ${templates_end} 2)
+        math(EXPR j "${i} + 1")
+        list(GET ARG_TEMPLATES ${i} tpl)
+        list(GET ARG_TEMPLATES ${j} out)
+        list(APPEND _template_args --template "${tpl}" "${out}")
+        list(APPEND _depends "${tpl}")
+        list(APPEND _outputs "${out}")
+    endforeach()
+
+    # Build --env args (user-defined template variables)
+    foreach(e IN LISTS ARG_ENV)
+        list(APPEND _env_args --env "${e}")
+    endforeach()
+
+    # Build command args
+    set(_args ${ARG_SPECS} ${_template_args} ${_env_args})
+    _append_if(ARG_PREFIX _args --prefix "${ARG_PREFIX}")
+
+    add_custom_command(
+        OUTPUT ${_outputs}
+        COMMAND ${JsmnTools_EXECUTABLE} generate ${_args}
+        DEPENDS ${ARG_SPECS} ${_depends}
+        COMMENT "jsmn-tools: generating outputs"
+    )
+
+    if(ARG_TARGET)
+        add_custom_target(${ARG_TARGET} DEPENDS ${_outputs})
+    endif()
+endfunction()

jsmn_tools-0.1.0/codegen/src/jsmn_tools/__init__.py

@@ -0,0 +1 @@
+"""jsmn-tools code generator."""

jsmn_tools-0.1.0/codegen/src/jsmn_tools/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m jsmn_tools`."""
+
+from jsmn_tools.cli import main
+
+main()

jsmn_tools-0.1.0/codegen/src/jsmn_tools/bundle.py

@@ -0,0 +1,128 @@
+"""Workspace parsing utilities"""
+
+import re
+from pathlib import Path
+from typing import NamedTuple, TypedDict, cast
+
+from jsonschema import validate  # type: ignore[import-untyped]
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+from ruamel.yaml import YAML
+
+# safe yaml loader for schemas
+yaml = YAML(typ="safe")
+
+# regex for finding jsmn-tools file
+RE_CONFIG = re.compile(r"^\.?(jsmnTools|JsmnTools|jsmn-tools).ya?ml$")
+
+# regex for validating $id URIs: scheme://module/resource/vN
+RE_URI = re.compile(
+    r"^[a-zA-Z][a-zA-Z0-9-]*://[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+/v\d+$"
+)
+
+
+# validator support
+SCHEMA = yaml.load("""
+    type: object
+    required: [resources]
+    properties:
+        resources:
+            type: array
+            items:
+                type: object
+                required: [name, version]
+                properties:
+                    name:
+                        type: string
+                    version:
+                        type: number
+                    openapi:
+                        type: array
+                        items:
+                            type: string
+                    asyncapi:
+                        type: array
+                        items:
+                            type: string
+                    if:
+                        type: array
+                        items:
+                            type: string
+""")
+
+
+class ResourceConfig(TypedDict):
+    name: str
+    version: int
+    openapi: list[Path]
+    asyncapi: list[Path]
+
+
+class Config(TypedDict):
+    name: str
+    resources: list[ResourceConfig]
+
+
+class Uri(NamedTuple):
+    module: str
+    resource: str
+    version: int
+
+
+def _parse_workspace(path: Path | str, config: Path) -> Config:
+    root = Path(path).absolute()
+    name = root.name.split(".")[0]
+    doc = yaml.load(root / config)
+    validate(instance=doc, schema=SCHEMA)
+    doc["name"] = name
+    for res in doc["resources"]:
+        if "openapi" in res:
+            res["openapi"] = [root / path for path in res["openapi"]]
+        else:
+            res["openapi"] = []
+        if "asyncapi" in res:
+            res["asyncapi"] = [root / path for path in res["asyncapi"]]
+        else:
+            res["asyncapi"] = []
+    return cast("Config", doc)
+
+
+class InvalidUriError(Exception):
+    """Raised when a schema $id does not match the expected URI format."""
+
+
+def _read_resource(
+    loc: str | Path,
+    scheme: str,
+    module: str,
+    res: str,
+    version: int,
+) -> Resource:
+    content = yaml.load(loc)
+    if "$id" not in content:
+        content["$id"] = f"{scheme}://{module}/{res}/v{version}"
+    elif not RE_URI.match(content["$id"]):
+        # TODO need to collect errors instead of failing fast
+        raise InvalidUriError("Invalid $id: \"content['$id']\"")
+    return Resource.from_contents(content, default_specification=DRAFT202012)
+
+
+def bundle(scheme: str, workspace: list[Path] | list[str]) -> Registry:
+    """ """
+
+    # iterate over workspace directories, parsing specifications
+    configs = [
+        _parse_workspace(module, path)
+        for module in workspace
+        for path in Path(module).iterdir()
+        if RE_CONFIG.match(path.name)
+    ]
+
+    # flatten resources into a keyable registry
+    content = [
+        _read_resource(spec, scheme, cfg["name"], res["name"], res["version"])
+        for cfg in configs
+        for res in cfg["resources"]
+        for spec in res["openapi"]
+    ]
+    return content @ Registry()

jsmn_tools-0.1.0/codegen/src/jsmn_tools/cli.py

@@ -0,0 +1,105 @@
+"""CLI entry point for jsmn tools cli"""
+
+import argparse
+import sys
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+from ruamel.yaml import YAML
+
+from jsmn_tools.lang.jsmn.flatten import flatten_with_resolver
+from jsmn_tools.lang.jsmn.render import Renderer
+
+JSMN_RUNTIME_DIR = files("jsmn_tools").joinpath("lang", "jsmn", "runtime")
+RUNTIME_FILES = ("runtime.c", "runtime.h", "jsmn.h")
+
+yaml = YAML(typ="safe")
+
+
+def parse_spec(p: str) -> Resource:
+    y = yaml.load(Path(p))
+    return Resource.from_contents(y, default_specification=DRAFT202012)
+
+
+def _die(fmt: str, *args: object) -> None:
+    print(f"error: {fmt % args}" if args else f"error: {fmt}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _cmake_dir() -> str:
+    pkg = files("jsmn_tools").joinpath("cmake")
+    if Path(str(pkg)).is_dir():
+        return str(pkg)
+    # Editable install: cmake/ lives at repo root, not inside the package.
+    repo = Path(__file__).resolve().parents[3]
+    fallback = repo / "cmake" / "modules"
+    if fallback.is_dir():
+        return str(fallback)
+    raise FileNotFoundError("Cannot locate jsmn tools cmake modules")
+
+
+def _generate(args: argparse.Namespace) -> None:
+    resources = [parse_spec(s) for s in args.specs]
+    extra_env = dict(e.split("=", 1) for e in args.env)
+    registry: Registry[Any] = resources @ Registry()
+    specs = [r.contents for r in registry.values()]
+    compiled = flatten_with_resolver(*specs, resolver=registry.resolver())
+    opts: dict[str, Any] = {"extra_env": extra_env}
+    if args.prefix:
+        opts["prefix"] = args.prefix
+    renderer = Renderer(compiled.decls, **opts)
+    for src, out in args.templates:
+        tpl = Path(src).read_text(encoding="utf-8")
+        Path(out).write_text(renderer.render(tpl), encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="jsmn-tools", description="jsmn tools")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Top level commands
+    parser.add_argument(
+        "--cmake-dir",
+        action="store_true",
+        help="Print cmake module install path",
+    )
+
+    # Code generator sub command
+    gen_parser = subparsers.add_parser("generate", help="template renderer")
+    gen_parser.add_argument("specs", nargs="*", help="YAML spec files")
+    gen_parser.add_argument(
+        "--template",
+        nargs=2,
+        action="append",
+        metavar=("TEMPLATE", "OUTPUT"),
+        dest="templates",
+        default=[],
+        help="Template and output filename pair",
+    )
+    gen_parser.add_argument(
+        "--env",
+        action="append",
+        metavar="KEY=VALUE",
+        default=[],
+        help="User-defined template variable",
+    )
+    gen_parser.add_argument(
+        "--prefix",
+        help="Function/type prefix (default: jsmn_)",
+    )
+
+    args = parser.parse_args()
+    if args.cmake_dir:
+        print(_cmake_dir())
+    elif args.command == "generate":
+        _generate(args)
+    else:
+        parser.print_help()
+        _die("no command specified")
+
+
+if __name__ == "__main__":
+    main()