nginx-lint-plugin 0.25.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,32 @@
1
+ from typing import TypeVar, Generic, Union
2
+ from dataclasses import dataclass
3
+
4
+ S = TypeVar('S')
5
+ @dataclass
6
+ class Some(Generic[S]):
7
+ """Represents the "present" (i.e. non-absent) case of an optional value.
8
+
9
+ This is used to disambiguate values of a nested ComponentModel `option` type
10
+ (e.g. `option<option<T>>` or similar). Non-nested `option` values are
11
+ represented using `typing.Optional`, i.e. nullable types.
12
+
13
+ """
14
+ value: S
15
+
16
+ T = TypeVar('T')
17
+ @dataclass
18
+ class Ok(Generic[T]):
19
+ """Represents the success case of a Component Model `result` value."""
20
+ value: T
21
+
22
+ E = TypeVar('E')
23
+ @dataclass(frozen=True)
24
+ class Err(Generic[E], Exception):
25
+ """Represents the failure case of a Component Model `result` value."""
26
+ value: E
27
+
28
+ Result = Union[Ok[T], Err[E]]
29
+ """Represents a Component Model `result` value, i.e. a variant type representing
30
+ either success payload or failure payload.
31
+
32
+ """
@@ -0,0 +1,103 @@
1
+ """Python SDK for nginx-lint WASM plugins.
2
+
3
+ Mirrors the TypeScript SDK at plugins/typescript/nginx-lint-plugin/:
4
+ provides guest-side Config reconstruction (`build_config_from_snapshot`),
5
+ constructors for the WIT record types, and testing utilities
6
+ (`nginx_lint_plugin.testing`).
7
+
8
+ Everything a plugin needs is re-exported here, so plugin code imports from
9
+ this package rather than reaching into the generated bindings:
10
+
11
+ from nginx_lint_plugin import Rule, define_rules, error_builder, plugin_spec
12
+
13
+ class MyRule(Rule):
14
+ spec = plugin_spec("my-rule", "style", "...", severity="warning")
15
+ relevant_directives = ["some_directive"]
16
+
17
+ def check(self, cfg, path):
18
+ ...
19
+
20
+ WitWorld = define_rules(MyRule())
21
+ """
22
+
23
+ from pathlib import Path
24
+
25
+ from wit_world.imports.config_api import (
26
+ Config,
27
+ ConfigItem,
28
+ ConfigSnapshot,
29
+ Directive,
30
+ DirectiveContext,
31
+ )
32
+ from wit_world.imports.data_types import (
33
+ ArgumentInfo,
34
+ ArgumentType,
35
+ BlankLineInfo,
36
+ CommentInfo,
37
+ DirectiveData,
38
+ )
39
+ from wit_world.imports.types import Fix, LintError, PluginSpec, Severity
40
+
41
+ from .builders import ErrorBuilder, error_builder, plugin_spec
42
+ from .config_builder import (
43
+ ReconstructedConfig,
44
+ build_config_from_parse_output,
45
+ build_config_from_snapshot,
46
+ )
47
+ from .rules import Rule, define_rules
48
+
49
+ # Keep in sync with API_VERSION in crates/nginx-lint-plugin/src/types.rs
50
+ API_VERSION = "1.2"
51
+
52
+
53
+ def wit_dir() -> Path:
54
+ """Return the directory holding the bundled `nginx-lint-plugin.wit`.
55
+
56
+ componentize-py needs the interface definition to build a plugin, so the
57
+ SDK ships it. Pass this to its `-d` option:
58
+
59
+ componentize-py -d "$(python -c 'import nginx_lint_plugin as p; print(p.wit_dir())')" \\
60
+ -w plugin-rules componentize app -o plugin.wasm --stub-wasi
61
+
62
+ Raises FileNotFoundError if the installed package has no bundled WIT,
63
+ which happens when it was built without the Makefile's `copy-wit` step
64
+ (the directory is generated, not committed). Failing here names the
65
+ cause; returning the path would surface it as an opaque componentize-py
66
+ error about a missing directory.
67
+ """
68
+ directory = Path(__file__).parent / "wit"
69
+ if not directory.is_dir():
70
+ raise FileNotFoundError(
71
+ f"nginx-lint-plugin was installed without its bundled WIT ({directory} "
72
+ "does not exist). Reinstall it with `make install` from the SDK "
73
+ "directory, which copies the WIT in before building."
74
+ )
75
+ return directory
76
+
77
+
78
+ __all__ = [
79
+ "API_VERSION",
80
+ "ArgumentInfo",
81
+ "ArgumentType",
82
+ "BlankLineInfo",
83
+ "CommentInfo",
84
+ "Config",
85
+ "ConfigItem",
86
+ "ConfigSnapshot",
87
+ "Directive",
88
+ "DirectiveContext",
89
+ "DirectiveData",
90
+ "ErrorBuilder",
91
+ "Fix",
92
+ "LintError",
93
+ "PluginSpec",
94
+ "ReconstructedConfig",
95
+ "Rule",
96
+ "Severity",
97
+ "build_config_from_parse_output",
98
+ "build_config_from_snapshot",
99
+ "define_rules",
100
+ "error_builder",
101
+ "plugin_spec",
102
+ "wit_dir",
103
+ ]
@@ -0,0 +1,89 @@
1
+ """The parser and the fix applier, run as core wasm modules under wasmtime.
2
+
3
+ These are the Go SDK's test-helper modules (``plugins/go/nginx-lint-plugin/
4
+ nginxlinttest/{parser,fixer}.wasm``): ``nginx-lint-parser`` and
5
+ ``nginx-lint-common`` built with ``--features wasm-json``, committed there and
6
+ copied into this package by ``make copy-testkit``. They have no imports and
7
+ no canonical ABI — one JSON string in, one out — so wasmtime's core-module
8
+ API runs them. Reusing that committed, freshness-checked pair is why this
9
+ does not run the parser component through ``wasmtime.component`` instead.
10
+
11
+ Only ``testing`` imports this module. wasmtime is a native extension, so a
12
+ module a plugin imports must never reach it: componentize-py executes the
13
+ plugin's imports at build time and would fail to load it.
14
+ """
15
+
16
+ import functools
17
+ from pathlib import Path
18
+
19
+ import wasmtime
20
+
21
+ _WASM_DIR = Path(__file__).parent / "wasm"
22
+
23
+
24
+ @functools.cache
25
+ def _engine() -> wasmtime.Engine:
26
+ return wasmtime.Engine()
27
+
28
+
29
+ @functools.cache
30
+ def _module(name: str) -> wasmtime.Module:
31
+ # Compiling is the expensive part and the modules are stateless between
32
+ # calls, so each is compiled once per process and instantiated per call.
33
+ path = _WASM_DIR / f"{name}.wasm"
34
+ if not path.is_file():
35
+ raise RuntimeError(
36
+ f"{path} is missing; inside the repository run `make install` "
37
+ "(or `make copy-testkit`) in plugins/python/nginx-lint-plugin"
38
+ )
39
+ return wasmtime.Module.from_file(_engine(), str(path))
40
+
41
+
42
+ def call(module: str, export: str, *args: bytes) -> bytes:
43
+ """Run one JSON entry point of the ``parser`` or ``fixer`` module.
44
+
45
+ Each argument is written into the module's memory and passed as a
46
+ (pointer, length) pair; the export returns its result packed into one
47
+ u64, ``(ptr << 32) | len``.
48
+ """
49
+ # A fresh instance per call, so one parse cannot see what a previous one
50
+ # left in the module's memory.
51
+ store = wasmtime.Store(_engine())
52
+ instance = wasmtime.Instance(store, _module(module), [])
53
+ exports = instance.exports(store)
54
+ memory = exports["memory"]
55
+ alloc = exports["alloc"]
56
+ entry = exports[export]
57
+ assert isinstance(memory, wasmtime.Memory)
58
+ assert isinstance(alloc, wasmtime.Func)
59
+ assert isinstance(entry, wasmtime.Func)
60
+
61
+ params: list[int] = []
62
+ for arg in args:
63
+ if not arg:
64
+ params += [0, 0]
65
+ continue
66
+ ptr = alloc(store, len(arg))
67
+ memory.write(store, arg, ptr)
68
+ params += [ptr, len(arg)]
69
+
70
+ return _read(store, memory, entry(store, *params))
71
+
72
+
73
+ def version(module: str) -> str:
74
+ """The version of the crate the module was built from."""
75
+ store = wasmtime.Store(_engine())
76
+ instance = wasmtime.Instance(store, _module(module), [])
77
+ exports = instance.exports(store)
78
+ memory = exports["memory"]
79
+ entry = exports["version"]
80
+ assert isinstance(memory, wasmtime.Memory)
81
+ assert isinstance(entry, wasmtime.Func)
82
+ return _read(store, memory, entry(store)).decode()
83
+
84
+
85
+ def _read(store: wasmtime.Store, memory: wasmtime.Memory, packed: int) -> bytes:
86
+ # An i64 comes back signed; the pair is two unsigned 32-bit halves.
87
+ packed &= 0xFFFF_FFFF_FFFF_FFFF
88
+ ptr, length = packed >> 32, packed & 0xFFFF_FFFF
89
+ return memory.read(store, ptr, ptr + length)
@@ -0,0 +1,133 @@
1
+ """Constructors for the WIT record types.
2
+
3
+ The generated dataclasses have no defaults, so building a `PluginSpec`
4
+ means spelling out all eleven fields (five of them usually `None`) and
5
+ every `LintError` repeats the plugin's own rule and category. These
6
+ helpers mirror the Rust SDK's `PluginSpec::new()` / `with_*()` and
7
+ `spec().error_builder()` so plugin code reads the same in both languages.
8
+ """
9
+
10
+ from typing import List, Optional, Protocol
11
+
12
+ from wit_world.imports.types import Fix, LintError, PluginSpec, Severity
13
+
14
+
15
+ class _HasPosition(Protocol):
16
+ """The part of the `directive` resource the error builder needs."""
17
+
18
+ def line(self) -> int: ...
19
+
20
+ def column(self) -> int: ...
21
+
22
+
23
+ def plugin_spec(
24
+ name: str,
25
+ category: str,
26
+ description: str,
27
+ *,
28
+ api_version: Optional[str] = None,
29
+ severity: Optional[str] = None,
30
+ why: Optional[str] = None,
31
+ bad_example: Optional[str] = None,
32
+ good_example: Optional[str] = None,
33
+ references: Optional[List[str]] = None,
34
+ min_nginx_version: Optional[str] = None,
35
+ max_nginx_version: Optional[str] = None,
36
+ ) -> PluginSpec:
37
+ """Build a :class:`PluginSpec`, defaulting the optional fields.
38
+
39
+ ``api_version`` defaults to the SDK's :data:`API_VERSION`, so a plugin
40
+ does not have to repeat (and cannot drift from) the version it was
41
+ built against.
42
+ """
43
+ from . import API_VERSION
44
+
45
+ return PluginSpec(
46
+ name=name,
47
+ category=category,
48
+ description=description,
49
+ api_version=api_version if api_version is not None else API_VERSION,
50
+ severity=severity,
51
+ why=why,
52
+ bad_example=bad_example,
53
+ good_example=good_example,
54
+ references=references,
55
+ min_nginx_version=min_nginx_version,
56
+ max_nginx_version=max_nginx_version,
57
+ )
58
+
59
+
60
+ class ErrorBuilder:
61
+ """Creates :class:`LintError`s with the rule and category pre-filled.
62
+
63
+ Obtain one with :func:`error_builder`, mirroring the Rust SDK's
64
+ ``spec().error_builder()``::
65
+
66
+ err = error_builder(self.spec())
67
+ errors.append(err.warning_at("message", ctx.directive))
68
+ """
69
+
70
+ def __init__(self, rule: str, category: str):
71
+ self._rule = rule
72
+ self._category = category
73
+
74
+ def _make(
75
+ self,
76
+ severity: Severity,
77
+ message: str,
78
+ line: Optional[int],
79
+ column: Optional[int],
80
+ fixes: Optional[List[Fix]],
81
+ ) -> LintError:
82
+ return LintError(
83
+ rule=self._rule,
84
+ category=self._category,
85
+ message=message,
86
+ severity=severity,
87
+ line=line,
88
+ column=column,
89
+ fixes=list(fixes) if fixes else [],
90
+ )
91
+
92
+ def error(
93
+ self,
94
+ message: str,
95
+ line: Optional[int] = None,
96
+ column: Optional[int] = None,
97
+ fixes: Optional[List[Fix]] = None,
98
+ ) -> LintError:
99
+ """Create an error at an explicit position."""
100
+ return self._make(Severity.ERROR, message, line, column, fixes)
101
+
102
+ def warning(
103
+ self,
104
+ message: str,
105
+ line: Optional[int] = None,
106
+ column: Optional[int] = None,
107
+ fixes: Optional[List[Fix]] = None,
108
+ ) -> LintError:
109
+ """Create a warning at an explicit position."""
110
+ return self._make(Severity.WARNING, message, line, column, fixes)
111
+
112
+ def error_at(
113
+ self,
114
+ message: str,
115
+ directive: _HasPosition,
116
+ fixes: Optional[List[Fix]] = None,
117
+ ) -> LintError:
118
+ """Create an error at a directive's position."""
119
+ return self.error(message, directive.line(), directive.column(), fixes)
120
+
121
+ def warning_at(
122
+ self,
123
+ message: str,
124
+ directive: _HasPosition,
125
+ fixes: Optional[List[Fix]] = None,
126
+ ) -> LintError:
127
+ """Create a warning at a directive's position."""
128
+ return self.warning(message, directive.line(), directive.column(), fixes)
129
+
130
+
131
+ def error_builder(spec: PluginSpec) -> ErrorBuilder:
132
+ """Return an :class:`ErrorBuilder` keyed on a spec's rule and category."""
133
+ return ErrorBuilder(spec.name, spec.category)