pragmatiks-lint 0.2.0__tar.gz

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,14 @@
1
+ .DS_Store
2
+ .ruff_cache/
3
+ .mypy_cache/
4
+ .pytest_cache/
5
+ .venv/
6
+ __pycache__/
7
+ *.py[cod]
8
+ python/dist/
9
+ python/build/
10
+ python/src/pragmatiks_lint/semgrep_rules/
11
+ js/node_modules/
12
+ js/dist/
13
+ js/src/semgrep-rules/
14
+ js/*.tgz
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 - 2026-05-10
4
+
5
+ - Scaffolded the unified `pragma-lint` mono-repo.
6
+ - Added shared semgrep rules in `rules/`.
7
+ - Added library-only Python package `pragmatiks-lint`.
8
+ - Added library-only npm package `@pragmatiks/lint`.
9
+ - Added build-time rule vendoring for both package artifacts.
10
+
11
+ ## python-v0.2.0 (2026-05-10)
12
+
13
+ ### Feat
14
+
15
+ - initial scaffold of pragma-lint v0.1.0 — unified mono-repo (PRA-418)
16
+
17
+ ### Fix
18
+
19
+ - address PRA-418 review feedback
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Pragmatiks
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,27 @@
1
+ Metadata-Version: 2.4
2
+ Name: pragmatiks-lint
3
+ Version: 0.2.0
4
+ Summary: Library API and bundled semgrep rules for Pragmatiks engineering principles
5
+ License-File: LICENSE
6
+ Classifier: Development Status :: 3 - Alpha
7
+ Classifier: Intended Audience :: Developers
8
+ Classifier: Programming Language :: Python :: 3.13
9
+ Classifier: Typing :: Typed
10
+ Requires-Python: >=3.13
11
+ Requires-Dist: pyyaml>=6.0.0
12
+ Requires-Dist: semgrep>=1.145.0
13
+ Description-Content-Type: text/markdown
14
+
15
+ # pragmatiks-lint
16
+
17
+ Python library for running Pragmatiks semgrep rules.
18
+
19
+ ```python
20
+ from pathlib import Path
21
+
22
+ from pragmatiks_lint import run_check
23
+
24
+ findings = run_check([Path("src")], language="python")
25
+ ```
26
+
27
+ This package has no CLI entry point. Command-line integration belongs in `pragma-cli`.
@@ -0,0 +1,13 @@
1
+ # pragmatiks-lint
2
+
3
+ Python library for running Pragmatiks semgrep rules.
4
+
5
+ ```python
6
+ from pathlib import Path
7
+
8
+ from pragmatiks_lint import run_check
9
+
10
+ findings = run_check([Path("src")], language="python")
11
+ ```
12
+
13
+ This package has no CLI entry point. Command-line integration belongs in `pragma-cli`.
@@ -0,0 +1,87 @@
1
+ [project]
2
+ name = "pragmatiks-lint"
3
+ version = "0.2.0"
4
+ description = "Library API and bundled semgrep rules for Pragmatiks engineering principles"
5
+ readme = "README.md"
6
+ requires-python = ">=3.13"
7
+ dependencies = [
8
+ "PyYAML>=6.0.0",
9
+ "semgrep>=1.145.0",
10
+ ]
11
+ classifiers = [
12
+ "Development Status :: 3 - Alpha",
13
+ "Intended Audience :: Developers",
14
+ "Programming Language :: Python :: 3.13",
15
+ "Typing :: Typed",
16
+ ]
17
+
18
+ [dependency-groups]
19
+ dev = [
20
+ "mypy>=1.18.0",
21
+ "pytest>=9.0.0",
22
+ "ruff>=0.14.0",
23
+ "types-PyYAML>=6.0.0",
24
+ ]
25
+
26
+ [tool.ruff]
27
+ target-version = "py313"
28
+ line-length = 120
29
+
30
+ [tool.ruff.lint]
31
+ preview = true
32
+ select = [
33
+ "E",
34
+ "W",
35
+ "F",
36
+ "I",
37
+ "PLC0415",
38
+ "UP",
39
+ "D",
40
+ "DOC",
41
+ ]
42
+
43
+ [tool.ruff.lint.pydocstyle]
44
+ convention = "google"
45
+
46
+ [tool.ruff.lint.isort]
47
+ lines-after-imports = 2
48
+ known-first-party = ["pragmatiks_lint"]
49
+
50
+ [tool.ruff.lint.per-file-ignores]
51
+ "tests/fixtures/*.py" = ["D100", "D103"]
52
+
53
+ [tool.ruff.format]
54
+ preview = true
55
+
56
+ [tool.mypy]
57
+ python_version = "3.13"
58
+ strict = true
59
+ files = ["src/pragmatiks_lint", "tests"]
60
+
61
+ [tool.pytest.ini_options]
62
+ testpaths = ["tests"]
63
+
64
+ [tool.commitizen]
65
+ name = "cz_conventional_commits"
66
+ version = "0.2.0"
67
+ version_files = ["pyproject.toml:^version"]
68
+ tag_format = "python-v$version"
69
+ update_changelog_on_bump = true
70
+ changelog_file = "CHANGELOG.md"
71
+
72
+ [tool.hatch.build.targets.wheel]
73
+ packages = ["src/pragmatiks_lint"]
74
+ include = ["src/pragmatiks_lint/semgrep_rules/*.yml"]
75
+
76
+ [tool.hatch.build.targets.sdist]
77
+ include = [
78
+ "CHANGELOG.md",
79
+ "LICENSE",
80
+ "src/pragmatiks_lint",
81
+ "README.md",
82
+ "pyproject.toml",
83
+ ]
84
+
85
+ [build-system]
86
+ requires = ["hatchling>=1.28.0"]
87
+ build-backend = "hatchling.build"
@@ -0,0 +1,8 @@
1
+ """Public library API for Pragmatiks lint rules."""
2
+
3
+ from pragmatiks_lint._rules import list_rules
4
+ from pragmatiks_lint.findings import Finding
5
+ from pragmatiks_lint.runner import Language, run_check
6
+
7
+
8
+ __all__ = ["Finding", "Language", "list_rules", "run_check"]
@@ -0,0 +1,48 @@
1
+ """Bundled semgrep rule discovery."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from contextlib import contextmanager
7
+ from importlib import resources
8
+ from pathlib import Path
9
+ from typing import Any, cast
10
+
11
+ import yaml
12
+
13
+
14
+ @contextmanager
15
+ def bundled_rules_directory() -> Iterator[Path]:
16
+ """Yield bundled semgrep rules as a real filesystem path."""
17
+ rules_reference = resources.files("pragmatiks_lint").joinpath("semgrep_rules")
18
+ with resources.as_file(rules_reference) as rules_directory:
19
+ yield rules_directory
20
+
21
+
22
+ def list_rules() -> list[str]:
23
+ """Return bundled semgrep rule identifiers."""
24
+ rules_reference = resources.files("pragmatiks_lint").joinpath("semgrep_rules")
25
+ rule_ids: list[str] = []
26
+ rule_files = sorted(
27
+ (path for path in rules_reference.iterdir() if path.name.endswith(".yml")), key=lambda path: path.name
28
+ )
29
+ for rule_file in rule_files:
30
+ rule_ids.extend(parse_rule_ids(rule_file.read_text()))
31
+ return sorted(rule_ids)
32
+
33
+
34
+ def parse_rule_ids(rule_text: str) -> list[str]:
35
+ """Return semgrep rule identifiers parsed from YAML text."""
36
+ payload = cast(dict[str, Any] | None, yaml.safe_load(rule_text))
37
+ if not payload:
38
+ return []
39
+
40
+ rules = payload.get("rules", [])
41
+ if not isinstance(rules, list):
42
+ return []
43
+
44
+ rule_ids: list[str] = []
45
+ for rule in rules:
46
+ if isinstance(rule, dict) and isinstance(rule.get("id"), str):
47
+ rule_ids.append(rule["id"])
48
+ return rule_ids
@@ -0,0 +1,21 @@
1
+ """Finding model returned by the library runner."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+
8
+ @dataclass(frozen=True)
9
+ class Finding:
10
+ """Structured semgrep finding."""
11
+
12
+ path: str
13
+ line: int
14
+ rule_id: str
15
+ severity: str
16
+ message: str
17
+
18
+ @property
19
+ def is_blocker(self) -> bool:
20
+ """Return whether the finding is a blocking semgrep error."""
21
+ return self.severity == "ERROR"
@@ -0,0 +1,83 @@
1
+ """Semgrep runner for bundled Pragmatiks rules."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import subprocess
7
+ from pathlib import Path
8
+ from typing import Any, Literal, cast
9
+
10
+ from pragmatiks_lint._rules import bundled_rules_directory
11
+ from pragmatiks_lint.findings import Finding
12
+
13
+
14
+ Language = Literal["python", "ts", "all"]
15
+
16
+
17
+ def run_check(paths: list[Path], language: Language = "all") -> list[Finding]:
18
+ """Run bundled semgrep rules against paths.
19
+
20
+ Returns:
21
+ Structured semgrep findings.
22
+
23
+ Raises:
24
+ RuntimeError: If semgrep times out or exits with an infrastructure error.
25
+ """
26
+ with bundled_rules_directory() as rules_directory:
27
+ command = [
28
+ "semgrep",
29
+ "--config",
30
+ str(rules_directory),
31
+ "--json",
32
+ "--quiet",
33
+ *language_includes(language),
34
+ *[str(path) for path in paths],
35
+ ]
36
+ try:
37
+ result = subprocess.run(command, capture_output=True, check=False, text=True, timeout=600)
38
+ except subprocess.TimeoutExpired as error:
39
+ raise RuntimeError("semgrep timed out after 600 seconds") from error
40
+
41
+ if result.returncode not in {0, 1}:
42
+ raise RuntimeError(result.stderr.strip() or "semgrep failed")
43
+
44
+ payload = cast(dict[str, Any], json.loads(result.stdout or '{"results": []}'))
45
+ findings = payload.get("results", [])
46
+ if not isinstance(findings, list):
47
+ return []
48
+ return [parse_finding(item) for item in findings if isinstance(item, dict)]
49
+
50
+
51
+ def language_includes(language: Language) -> list[str]:
52
+ """Return semgrep include arguments for one language mode."""
53
+ if language == "python":
54
+ return ["--include", "*.py"]
55
+ if language == "ts":
56
+ return ["--include", "*.ts", "--include", "*.tsx", "--include", "*.js", "--include", "*.jsx"]
57
+ return []
58
+
59
+
60
+ def parse_finding(item: dict[str, Any]) -> Finding:
61
+ """Convert a semgrep JSON result into a Finding.
62
+
63
+ Returns:
64
+ Structured finding with defaulted fields.
65
+ """
66
+ start = typed_mapping(item.get("start"))
67
+ extra = typed_mapping(item.get("extra"))
68
+ line_value = start.get("line", 1)
69
+
70
+ return Finding(
71
+ path=str(item.get("path", "")),
72
+ line=line_value if isinstance(line_value, int) else 1,
73
+ rule_id=str(item.get("check_id", "")),
74
+ severity=str(extra.get("severity", "INFO")),
75
+ message=str(extra.get("message", "")),
76
+ )
77
+
78
+
79
+ def typed_mapping(value: object) -> dict[str, object]:
80
+ """Return a string-key mapping when semgrep JSON gives one."""
81
+ if isinstance(value, dict):
82
+ return {str(key): item for key, item in value.items()}
83
+ return {}
@@ -0,0 +1,27 @@
1
+ rules:
2
+ - id: pra-env-read-deep
3
+ pattern-either:
4
+ - pattern: os.environ[$KEY]
5
+ - pattern: os.environ.get($KEY)
6
+ - pattern: os.getenv($KEY)
7
+ paths:
8
+ exclude:
9
+ - "settings.py"
10
+ - "config.py"
11
+ - "env.py"
12
+ - "__main__.py"
13
+ - "__init__.py"
14
+ - "app.py"
15
+ - "cli.py"
16
+ - "main.py"
17
+ - "*/settings.py"
18
+ - "*/config.py"
19
+ - "*/env.py"
20
+ - "*/__main__.py"
21
+ - "*/__init__.py"
22
+ - "*/app.py"
23
+ - "*/cli.py"
24
+ - "*/main.py"
25
+ message: "principle #8 Environment reads belong at app boundaries. Move the read to settings or config."
26
+ severity: WARNING
27
+ languages: [python]
@@ -0,0 +1,44 @@
1
+ rules:
2
+ - id: pra-io-prefix-mismatch
3
+ patterns:
4
+ - pattern-either:
5
+ - pattern: |
6
+ def $NAME(...):
7
+ ...
8
+ - pattern: |
9
+ async def $NAME(...):
10
+ ...
11
+ - metavariable-regex:
12
+ metavariable: $NAME
13
+ regex: '^(get|fetch|retrieve|load|save|read|write|query)_.*'
14
+ - pattern-not: |
15
+ def $NAME(...):
16
+ ...
17
+ await $CALL
18
+ ...
19
+ - pattern-not: |
20
+ async def $NAME(...):
21
+ ...
22
+ await $CALL
23
+ ...
24
+ - pattern-not: |
25
+ def $NAME(...):
26
+ ...
27
+ open(...)
28
+ ...
29
+ - pattern-not: |
30
+ def $NAME(...):
31
+ ...
32
+ httpx.$METHOD(...)
33
+ ...
34
+ - pattern-not: |
35
+ def $NAME(...):
36
+ ...
37
+ requests.$METHOD(...)
38
+ ...
39
+ - pattern-not-regex: '(?s)(database|session|connection|cursor|client)\.(execute|fetch|get|post|put|delete|query|read|write|save)\('
40
+ message: "principle #7 I/O-prefixed function appears pure. Rename it with compute, build, derive, format, or parse."
41
+ severity: WARNING
42
+ languages: [python]
43
+ metadata:
44
+ note: "Heuristic rule; false positives are expected for hidden I/O wrappers."
@@ -0,0 +1,21 @@
1
+ rules:
2
+ - id: pra-no-abbreviations-python
3
+ patterns:
4
+ - pattern-either:
5
+ - pattern: $NAME = $VALUE
6
+ - pattern: "def $NAME(...): ..."
7
+ - pattern: "async def $NAME(...): ..."
8
+ - pattern: "def $FUNC($NAME, ...): ..."
9
+ - pattern: "def $FUNC(..., $NAME, ...): ..."
10
+ - pattern: "async def $FUNC($NAME, ...): ..."
11
+ - pattern: "async def $FUNC(..., $NAME, ...): ..."
12
+ - pattern: "for $NAME in $ITERABLE: ..."
13
+ - pattern: "class $NAME(...): ..."
14
+ - pattern: "class $NAME: ..."
15
+ - pattern: self.$NAME = $VALUE
16
+ - metavariable-regex:
17
+ metavariable: $NAME
18
+ regex: '^(k8s|cfg|db|req|res|ctx|tmp|pkg|svc|mgr|repo|usr|pwd|idx|cnt|msg|err|btn|txt|num|val)$'
19
+ message: "principle #11 Abbreviated identifier hides meaning. Rename it with full words."
20
+ severity: WARNING
21
+ languages: [python]
@@ -0,0 +1,11 @@
1
+ rules:
2
+ - id: pra-no-block-comments-python
3
+ pattern-regex: '(?m)^[ \t]*#(?![ \t]*WHY:).*\n[ \t]*#(?![ \t]*WHY:).*$'
4
+ message: "principle #10 Block comments make code harder to trust. Delete the comment or replace it with one WHY line."
5
+ severity: ERROR
6
+ languages: [python]
7
+ - id: pra-no-block-comments-js
8
+ pattern-regex: '/\*(?!\*)[\s\S]*?\*/'
9
+ message: "principle #10 Block comments make code harder to trust. Delete the comment or replace it with one WHY line."
10
+ severity: ERROR
11
+ languages: [typescript, javascript]
@@ -0,0 +1,11 @@
1
+ rules:
2
+ - id: pra-no-todo-comments-python
3
+ pattern-regex: '(?i)#\s*(TODO(?!\(PRA-[0-9]+\))|FIXME|XXX)\b'
4
+ message: "principle #10 Planning comments decay. Link a Linear issue or remove the comment."
5
+ severity: ERROR
6
+ languages: [python]
7
+ - id: pra-no-todo-comments-js
8
+ pattern-regex: '(?i)(//|/\*)\s*(TODO(?!\(PRA-[0-9]+\))|FIXME|XXX)\b'
9
+ message: "principle #10 Planning comments decay. Link a Linear issue or remove the comment."
10
+ severity: ERROR
11
+ languages: [typescript, javascript]
@@ -0,0 +1,24 @@
1
+ rules:
2
+ - id: pra-srp-and-or-name
3
+ patterns:
4
+ - pattern-either:
5
+ - pattern: "def $NAME(...): ..."
6
+ - pattern: "async def $NAME(...): ..."
7
+ - metavariable-regex:
8
+ metavariable: $NAME
9
+ regex: '.*(_and_|_or_|[a-z0-9](And|Or)(?=[A-Z]|$)).*'
10
+ message: "principle #12 Compound function name violates SRP. Split the function by responsibility."
11
+ severity: ERROR
12
+ languages: [python]
13
+ - id: pra-srp-and-or-name-js
14
+ patterns:
15
+ - pattern-either:
16
+ - pattern: "function $NAME(...) { ... }"
17
+ - pattern: "async function $NAME(...) { ... }"
18
+ - pattern: "const $NAME = (...) => ..."
19
+ - metavariable-regex:
20
+ metavariable: $NAME
21
+ regex: '.*(_and_|_or_|[a-z0-9](And|Or)(?=[A-Z]|$)).*'
22
+ message: "principle #12 Compound function name violates SRP. Split the function by responsibility."
23
+ severity: ERROR
24
+ languages: [typescript, javascript]