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.
- componentize_py_types.py +32 -0
- nginx_lint_plugin/__init__.py +103 -0
- nginx_lint_plugin/_testkit.py +89 -0
- nginx_lint_plugin/builders.py +133 -0
- nginx_lint_plugin/config_builder.py +368 -0
- nginx_lint_plugin/include_context.py +41 -0
- nginx_lint_plugin/py.typed +0 -0
- nginx_lint_plugin/rules.py +123 -0
- nginx_lint_plugin/testing.py +320 -0
- nginx_lint_plugin/wasm/fixer.wasm +0 -0
- nginx_lint_plugin/wasm/parser.wasm +0 -0
- nginx_lint_plugin/wit/nginx-lint-plugin.wit +366 -0
- nginx_lint_plugin-0.25.0.dist-info/METADATA +210 -0
- nginx_lint_plugin-0.25.0.dist-info/RECORD +23 -0
- nginx_lint_plugin-0.25.0.dist-info/WHEEL +4 -0
- nginx_lint_plugin-0.25.0.dist-info/licenses/LICENSE +21 -0
- wit_world/__init__.py +48 -0
- wit_world/imports/__init__.py +0 -0
- wit_world/imports/config_api.py +286 -0
- wit_world/imports/data_types.py +89 -0
- wit_world/imports/parser_types.py +71 -0
- wit_world/imports/types.py +51 -0
- wit_world/py.typed +0 -0
componentize_py_types.py
ADDED
|
@@ -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)
|