vikela 4.6.0__py3-none-any.whl

vikela/__init__.py

@@ -0,0 +1,17 @@
+"""Vikela: optional development tooling, never a JsonPit runtime dependency."""
+__version__ = "4.6.0"
+
+
+def register(linter):
+	"""Pylint's plugin entry point; import its dependency only in plugin mode."""
+	from .pylint_plugin import MutationChecker
+	linter.register_checker(MutationChecker(linter))
+
+
+def load_ipython_extension(ipython):
+	from .notebook import cell_magic
+	ipython.register_magic_function(cell_magic, magic_kind="cell", magic_name="vikela")
+
+
+def unload_ipython_extension(ipython):
+	ipython.magics_manager.magics["cell"].pop("vikela", None)

vikela/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

vikela/analysis.py

@@ -0,0 +1,329 @@
+"""Conservative, non-executing JsonPit provenance analysis (CR077).
+
+Only resolved JsonPit imports/annotations and propagated values establish types.
+Unknown calls are not assumed to return a fresh or detached item. Branch joins
+retain facts only when all continuing paths agree. Loops join zero/one iteration;
+this is bounded analysis, not a proof about arbitrary Python execution.
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import asdict, dataclass, replace
+from typing import Iterable
+
+DOCS = "https://github.com/Burkhardt/vikela/blob/main/docs/rules.md"
+PROTECTED = {"id", "modified", "deleted"}
+
+
+@dataclass(frozen=True)
+class Finding:
+	rule: str
+	severity: str
+	path: str
+	line: int
+	column: int
+	reason: str
+	suggestion: str
+	documentation: str
+	cell: int | None = None
+	fix_available: bool = False
+
+	def to_dict(self):
+		return asdict(self)
+
+
+@dataclass(frozen=True)
+class Value:
+	kind: str = "unknown"
+	owner: str | None = None
+	key: str | None = None
+	fields: frozenset[str] = frozenset()
+	element: Value | None = None
+
+
+UNKNOWN = Value()
+ITEM_KINDS = {"live", "detached", "fresh", "item"}
+
+
+def path_name(node):
+	if isinstance(node, ast.Name): return node.id
+	if isinstance(node, ast.Attribute):
+		base = path_name(node.value)
+		return base + "." + node.attr if base else ""
+	return ""
+
+
+def literal(node):
+	return str(node.value) if isinstance(node, ast.Constant) and isinstance(node.value, str) else None
+
+
+def join_values(values):
+	values = list(values)
+	return values[0] if values and all(v == values[0] for v in values) else UNKNOWN
+
+
+class Analyzer:
+	def __init__(self, source: str, path: str = "<source>"):
+		self.tree = ast.parse(source, filename=path)
+		self.path = path
+		self.findings: list[Finding] = []
+		self.imports: dict[str, str] = {}
+		self.functions: dict[str, ast.FunctionDef | ast.AsyncFunctionDef] = {}
+		self.invalid: set[tuple[str | None, str | None]] = set()
+		self.depth = 0
+		self._seen = set()
+		self.scope = "module"
+
+	def qualified(self, node, env):
+		name = path_name(node)
+		head, _, tail = name.partition(".")
+		if head in env: return ""
+		return self.imports.get(head, head) + ("." + tail if tail else "")
+
+	def annotated(self, node, env, identity):
+		if isinstance(node, ast.Constant) and isinstance(node.value, str):
+			try: node = ast.parse(node.value, mode="eval").body
+			except SyntaxError: return UNKNOWN
+		name = self.qualified(node, env)
+		if name in {"jsonpit.Pit", "jsonpit.store.Pit"}: return Value("pit", identity)
+		if name in {"jsonpit.PitItem", "jsonpit.item.PitItem"}: return Value("item")
+		if isinstance(node, ast.Subscript):
+			element = self.annotated(node.slice, env, identity)
+			if self.qualified(node.value, env) in {"list", "set", "tuple", "typing.List", "typing.Sequence", "typing.Iterable"}:
+				return Value("collection", element=element)
+		return UNKNOWN
+
+	def emit(self, rule, node, reason):
+		key = (rule, node.lineno, node.col_offset, reason)
+		if key in self._seen: return
+		self._seen.add(key)
+		suggestion = (
+			"Update the same-owner live item through indexing or set_property; create a fresh PitItem containing only the intended fields for an explicit delta. Historical replay is not a client-write workaround."
+			if rule == "RAI011" else
+			"Let JsonPit manage Id, Modified and Deleted. Use rename_id or delete_item for lifecycle changes; update business properties through the live item."
+		)
+		self.findings.append(Finding(rule, "Warning", self.path, node.lineno, node.col_offset + 1,
+			reason, suggestion, DOCS + "#" + rule.lower()))
+
+	def payload_fields(self, node, env):
+		if isinstance(node, ast.Dict):
+			fields = set()
+			for key, value in zip(node.keys, node.values):
+				if key is None: fields.update(self.value(value, env).fields)
+				elif literal(key) is not None: fields.add(literal(key))
+			return frozenset(fields)
+		return self.value(node, env).fields
+
+	def payload_check(self, node, receiver, payload, env):
+		for field in self.payload_fields(payload, env):
+			if field.lower() in {"modified", "deleted"}:
+				self.emit("RAI012", node, f"Client mutation includes protected lifecycle attribute '{field}'.")
+			elif field.lower() == "id" and isinstance(payload, ast.Dict):
+				for key, val in zip(payload.keys, payload.values):
+					if literal(key) == field and literal(val) is not None and receiver.key is not None and literal(val) != receiver.key:
+						self.emit("RAI012", node, "Client mutation changes the item's immutable Id.")
+
+	def value(self, node, env):
+		if node is None: return UNKNOWN
+		name = path_name(node)
+		if name and name in env: return env[name]
+		if isinstance(node, ast.NamedExpr):
+			value = self.value(node.value, env); self.bind(node.target, value, env); return value
+		if isinstance(node, ast.Subscript):
+			base = self.value(node.value, env)
+			if base.kind == "pit": return Value("live", base.owner, literal(node.slice))
+			if base.kind == "collection": return base.element or UNKNOWN
+		if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+			return Value("collection", element=join_values(self.value(e, env) for e in node.elts) if node.elts else None)
+		if isinstance(node, ast.Dict): return Value("payload", fields=self.payload_fields(node, env))
+		if isinstance(node, ast.IfExp):
+			self.value(node.test, env)
+			return join_values([self.value(node.body, dict(env)), self.value(node.orelse, dict(env))])
+		if isinstance(node, ast.BoolOp): return join_values(self.value(v, env) for v in node.values)
+		if isinstance(node, ast.Call): return self.call(node, env)
+		if isinstance(node, ast.Await): return self.value(node.value, env)
+		return UNKNOWN
+
+	def call(self, node, env):
+		qualified = self.qualified(node.func, env)
+		args = [self.value(arg, env) for arg in node.args]
+		if qualified in {"jsonpit.Pit", "jsonpit.store.Pit"}:
+			return Value("pit", f"allocation:{self.scope}:{node.lineno}:{node.col_offset}")
+		if qualified in {"jsonpit.PitItem", "jsonpit.item.PitItem"}:
+			first = args[0] if args else UNKNOWN
+			key = literal(node.args[0]) if node.args else None
+			key = next((literal(k.value) for k in node.keywords if k.arg == "id"), key)
+			if first.kind in {"live", "detached"}: return replace(first, kind="detached")
+			if first.fields & {"Modified", "Deleted", "modified", "deleted"}:
+				return Value("detached", fields=first.fields)
+			return Value("fresh", key=key, fields=first.fields)
+		if qualified == "typing.cast" and len(args) == 2: return args[1]
+		if qualified in {"dict", "copy.copy", "copy.deepcopy"} and args:
+			return replace(args[0], kind="detached") if args[0].kind in ITEM_KINDS else args[0]
+		if isinstance(node.func, ast.Attribute):
+			receiver = self.value(node.func.value, env)
+			method = node.func.attr
+			if receiver.kind == "pit":
+				if method in {"get", "get_at"}:
+					explicit_none = any(k.arg == "at" and isinstance(k.value, ast.Constant) and k.value.value is None for k in node.keywords) or (method == "get_at" and len(node.args) > 1 and isinstance(node.args[1], ast.Constant) and node.args[1].value is None)
+					detached = method == "get_at" and not explicit_none or any(k.arg == "at" and not (isinstance(k.value, ast.Constant) and k.value.value is None) for k in node.keywords)
+					return Value("detached" if detached else "live", receiver.owner, literal(node.args[0]) if node.args else None)
+				if method == "add" and args:
+					value = args[0]
+					if value.kind == "detached": self.emit("RAI011", node, "A detached full projection is being submitted as a live write; it can replay unrelated fields and engine lifecycle metadata.")
+					elif value.kind == "live":
+						if (value.owner, value.key) in self.invalid or (value.owner, "*") in self.invalid:
+							self.emit("RAI011", node, "The live handle belongs to a deleted item or disposed Pit lifetime.")
+						elif value.owner != receiver.owner and all((o or "").startswith("allocation:") for o in [value.owner, receiver.owner]):
+							self.emit("RAI011", node, "The live handle belongs to a different Pit instance.")
+					if value.kind == "fresh":
+						# A first Add adopts the original item; subsequent aliases share it.
+						for name, old in list(env.items()):
+							if old is value: env[name] = Value("live", receiver.owner, old.key)
+				if method == "delete_item" and node.args and literal(node.args[0]) is not None:
+					self.invalid.add((receiver.owner, literal(node.args[0])))
+				if method in {"close", "dispose"}: self.invalid.add((receiver.owner, "*"))
+			elif receiver.kind in ITEM_KINDS:
+				if method in {"to_dict", "clone", "copy", "__copy__", "__deepcopy__"}: return replace(receiver, kind="detached")
+				if method in {"extend_with", "set_property", "merge"} and node.args:
+					self.payload_check(node, receiver, node.args[0], env)
+				if method in {"delete_property", "delete_property_path", "pop", "__delitem__"} and node.args:
+					field = literal(node.args[0])
+					if field and field.split(".")[0].lower() in PROTECTED:
+						self.emit("RAI012", node, f"Cannot delete protected lifecycle attribute '{field}'.")
+			elif receiver.kind == "collection" and method in {"append", "add", "extend"} and args:
+				name = path_name(node.func.value)
+				new = args[0].element if method == "extend" else args[0]
+				old = receiver.element
+				combined = new if old is None else join_values([old, new or UNKNOWN])
+				for alias, value in list(env.items()):
+					if value is receiver: env[alias] = replace(receiver, element=combined)
+		function = self.functions.get(path_name(node.func))
+		if function is not None and self.depth < 4:
+			local = dict(env)
+			for param, val in zip(function.args.args, args): local[param.arg] = val
+			self.depth += 1
+			invalid = set(self.invalid)
+			try:
+				returns, _ = self.block(function.body, local)
+				assigned = {path_name(target) for statement in ast.walk(function) if isinstance(statement, ast.Assign) for target in statement.targets}
+				for param, original in zip(function.args.args, args):
+					current = local.get(param.arg, UNKNOWN)
+					if param.arg not in assigned and (original.kind == "collection" or original.kind == "fresh" and current.kind == "live"):
+						for name, value in list(env.items()):
+							if value is original: env[name] = current
+				return join_values(returns)
+			finally: self.invalid = invalid; self.depth -= 1
+		return UNKNOWN
+
+	def bind(self, target, value, env):
+		name = path_name(target)
+		if name: env[name] = value
+		elif isinstance(target, (ast.Tuple, ast.List)):
+			for element in target.elts: self.bind(element, UNKNOWN, env)
+
+	def assignment(self, target, value, env):
+		if isinstance(target, (ast.Subscript, ast.Attribute)):
+			base = self.value(target.value, env)
+			field = literal(target.slice) if isinstance(target, ast.Subscript) else target.attr
+			if base.kind in ITEM_KINDS and field and field.lower() in PROTECTED:
+				self.emit("RAI012", target, f"Direct assignment changes protected lifecycle attribute '{field}'.")
+		self.bind(target, value, env)
+
+	def merge_env(self, target, branches):
+		for key in set().union(*(b.keys() for b in branches)):
+			target[key] = join_values(b.get(key, UNKNOWN) for b in branches)
+
+	def block(self, statements, env):
+		returns = []
+		for statement in statements:
+			if isinstance(statement, ast.Import):
+				for alias in statement.names:
+					name = alias.asname or alias.name.split(".")[0]; env.pop(name, None)
+					self.imports[name] = alias.name if alias.asname else alias.name.split(".")[0]
+			elif isinstance(statement, ast.ImportFrom):
+				for alias in statement.names:
+					name = alias.asname or alias.name; env.pop(name, None)
+					self.imports[name] = (statement.module or "") + "." + alias.name
+			elif isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+				self.functions[statement.name] = statement
+				env[statement.name] = UNKNOWN
+			elif isinstance(statement, ast.ClassDef):
+				env[statement.name] = UNKNOWN
+				local = dict(env)
+				for member in statement.body:
+					if isinstance(member, ast.AnnAssign):
+						name = path_name(member.target)
+						local["self." + name] = self.value(member.value, local) if member.value else self.annotated(member.annotation, local, "field:" + statement.name + "." + name)
+				self.analyze_functions(statement.body, local)
+			elif isinstance(statement, ast.Assign):
+				value = self.value(statement.value, env)
+				for target in statement.targets: self.assignment(target, value, env)
+			elif isinstance(statement, ast.AnnAssign):
+				value = self.value(statement.value, env) if statement.value else self.annotated(statement.annotation, env, "annotation:" + self.scope + ":" + path_name(statement.target))
+				self.assignment(statement.target, value, env)
+			elif isinstance(statement, ast.AugAssign):
+				self.value(statement.value, env); self.assignment(statement.target, UNKNOWN, env)
+			elif isinstance(statement, ast.Expr): self.value(statement.value, env)
+			elif isinstance(statement, ast.Return):
+				returns.append(self.value(statement.value, env)); return returns, True
+			elif isinstance(statement, ast.Raise): self.value(statement.exc, env); return returns, True
+			elif isinstance(statement, ast.If):
+				self.value(statement.test, env)
+				branches = []; before = set(self.invalid); invalids = []
+				for body in [statement.body, statement.orelse]:
+					local = dict(env); self.invalid = set(before)
+					values, stopped = self.block(body, local); returns.extend(values)
+					if not stopped: branches.append(local); invalids.append(set(self.invalid))
+				self.invalid = set.intersection(*invalids) if invalids else before
+				if not branches: return returns, True
+				self.merge_env(env, branches)
+			elif isinstance(statement, (ast.For, ast.AsyncFor, ast.While)):
+				local = dict(env); before = set(self.invalid)
+				if isinstance(statement, (ast.For, ast.AsyncFor)):
+					iterable = self.value(statement.iter, env); self.bind(statement.target, iterable.element or UNKNOWN, local)
+				self.block(statement.body, local)
+				self.invalid = before; self.merge_env(env, [env.copy(), local])
+				self.block(statement.orelse, env)
+			elif isinstance(statement, (ast.With, ast.AsyncWith)):
+				for item in statement.items:
+					value = self.value(item.context_expr, env)
+					if item.optional_vars: self.bind(item.optional_vars, value, env)
+				values, stopped = self.block(statement.body, env); returns.extend(values)
+				if stopped: return returns, True
+			elif isinstance(statement, ast.Delete):
+				for target in statement.targets:
+					if isinstance(target, ast.Subscript):
+						base = self.value(target.value, env); field = literal(target.slice)
+						if base.kind in ITEM_KINDS and field and field.lower() in PROTECTED: self.emit("RAI012", target, f"Cannot delete protected lifecycle attribute '{field}'.")
+					else: env.pop(path_name(target), None)
+			elif isinstance(statement, (ast.Break, ast.Continue)): return returns, True
+			elif isinstance(statement, ast.Try):
+				before = dict(env); before_invalid = set(self.invalid); branches = []
+				for body in [statement.body, *(handler.body for handler in statement.handlers)]:
+					local = dict(before); self.invalid = set(before_invalid); self.block(body, local); branches.append(local)
+				self.invalid = before_invalid; self.merge_env(env, branches)
+				self.block(statement.orelse, env); self.block(statement.finalbody, env)
+		return returns, False
+
+	def analyze_functions(self, statements, base):
+		for node in statements:
+			if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): continue
+			self.functions[node.name] = node
+		for node in statements:
+			if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): continue
+			local = dict(base); self.scope = node.name; before = set(self.invalid)
+			before_imports = dict(self.imports); before_functions = dict(self.functions)
+			for param in [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]:
+				local[param.arg] = self.annotated(param.annotation, base, "parameter:" + node.name + ":" + param.arg)
+			self.block(node.body, local)
+			self.analyze_functions(node.body, local)
+			self.invalid = before; self.imports = before_imports; self.functions = before_functions
+
+	def run(self):
+		env = {}; self.block(self.tree.body, env); self.analyze_functions(self.tree.body, env)
+		return sorted(self.findings, key=lambda f: (f.line, f.column, f.rule))
+
+
+def analyze(source: str, path: str = "<source>") -> list[Finding]:
+	return Analyzer(source, path).run()

vikela/cli.py

@@ -0,0 +1,116 @@
+"""Standalone, read-only-by-default CLI. No inspected code is imported or run."""
+from __future__ import annotations
+import argparse
+from dataclasses import replace
+import json
+from pathlib import Path
+import sys
+import tokenize
+
+from . import __version__
+from .analysis import Finding, analyze
+from .config import ConfigurationError, disabled_rules
+from .style import banner, enabled, help_text, paint
+
+
+class UsageError(ValueError): pass
+
+
+class Parser(argparse.ArgumentParser):
+	def error(self, message): raise UsageError(message)
+
+
+def parser():
+	p = Parser(prog="vikela", add_help=False)
+	p.add_argument("paths", nargs="*")
+	p.add_argument("-h", "--help", action="store_true")
+	p.add_argument("-v", "--version", action="store_true")
+	p.add_argument("-n", "--nologo", action="store_true")
+	p.add_argument("--json", action="store_true")
+	p.add_argument("--fix", "--qondisa", dest="fix", action="store_true")
+	p.add_argument("--config")
+	p.add_argument("--disable", action="append", choices=["RAI011", "RAI012"], default=[])
+	return p
+
+
+def sources(path):
+	if path.suffix == ".ipynb":
+		try:
+			notebook = json.loads(path.read_text(encoding="utf-8"))
+			if not isinstance(notebook, dict) or not isinstance(notebook.get("cells"), list):
+				raise UsageError(f"{path}: notebook must contain a cells array")
+			# One non-executed source stream retains cross-cell provenance in document order.
+			chunks = []; locations = []
+			for index, cell in enumerate(notebook["cells"], 1):
+				if not isinstance(cell, dict): raise UsageError(f"{path}: malformed cell {index}")
+				if cell.get("cell_type") != "code": continue
+				text = cell.get("source", "")
+				if isinstance(text, list) and all(isinstance(s, str) for s in text): text = "".join(text)
+				if not isinstance(text, str): raise UsageError(f"{path}: malformed source in cell {index}")
+				for line_number, line in enumerate(text.splitlines(), 1):
+					# Ignore IPython commands without executing them; cell bodies remain Python.
+					chunks.append("" if line.lstrip().startswith(("%", "!")) else line)
+					locations.append((index, line_number))
+			yield "\n".join(chunks), locations
+		except (json.JSONDecodeError, UnicodeError) as exc: raise UsageError(f"{path}: {exc}") from exc
+	else:
+		with tokenize.open(path) as stream: yield stream.read(), None
+
+
+def inspect_paths(paths, disabled=(), config=None):
+	files = set()
+	for value in paths:
+		path = Path(value).expanduser()
+		if not path.exists(): raise UsageError(f"Path does not exist: {path}")
+		if path.is_dir():
+			files.update(p for p in path.rglob("*") if p.suffix in {".py", ".ipynb"} and not any(x in {".git", ".venv", "venv", "__pycache__"} for x in p.parts))
+		elif path.suffix in {".py", ".ipynb"}: files.add(path)
+		else: raise UsageError(f"Unsupported input type: {path}")
+	findings = []
+	for path in sorted(files):
+		ignored = set(disabled) | disabled_rules(path, config)
+		for source, locations in sources(path):
+			try: items = analyze(source, str(path.resolve()))
+			except SyntaxError as exc:
+				cell = f" cell {locations[exc.lineno - 1][0]}" if locations and exc.lineno and exc.lineno <= len(locations) else ""
+				raise UsageError(f"{path}{cell}:{exc.lineno}:{exc.offset}: {exc.msg}") from exc
+			for item in items:
+				if item.rule in ignored: continue
+				if locations:
+					cell, line = locations[item.line - 1]; item = replace(item, cell=cell, line=line)
+				findings.append(item)
+	return findings
+
+
+def render(findings, json_mode=False, nologo=False, fix=False):
+	if json_mode:
+		print(json.dumps([f.to_dict() for f in findings], ensure_ascii=False, indent=2))
+	else:
+		color = enabled()
+		if not nologo: print(banner(color))
+		for finding in findings:
+			cell = f" [cell {finding.cell}]" if finding.cell is not None else ""
+			print(f"{finding.path}{cell}:{finding.line}:{finding.column}: " + paint(finding.rule, "1;94", color) + " " + finding.reason)
+			print("  " + paint("Suggestion: ", "3;35", color) + finding.suggestion)
+			print("  " + finding.documentation)
+		if not findings: print(paint("✓ No mutation guardrail findings.", "92", color))
+	if fix and findings:
+		print("No proven safe automatic transformation is available for these findings; source files were left unchanged.", file=sys.stderr)
+
+
+def main(argv=None):
+	json_mode = "--json" in (sys.argv[1:] if argv is None else argv)
+	try:
+		args = parser().parse_args(argv)
+		if args.help: print(help_text()); return 0
+		if args.version: print(f"vikela v{__version__}"); return 0
+		if not args.paths: raise UsageError("Specify a Python file, notebook or directory; use --help for options.")
+		findings = inspect_paths(args.paths, args.disable, args.config)
+		render(findings, args.json, args.nologo, args.fix)
+		return 1 if findings else 0
+	except (UsageError, ConfigurationError, SyntaxError, UnicodeError) as exc:
+		if json_mode: print("[]")
+		print(f"vikela: {exc}", file=sys.stderr); return 2
+	except Exception as exc:
+		if json_mode: print("[]")
+		print(f"vikela: {type(exc).__name__}: {exc}", file=sys.stderr); return 4

vikela/config.py

@@ -0,0 +1,33 @@
+"""Shared standalone/editor project configuration; no inspected modules are imported."""
+from pathlib import Path
+import tomllib
+
+
+class ConfigurationError(ValueError): pass
+
+
+def disabled_rules(path, explicit=None):
+	if explicit is not None:
+		candidates = [Path(explicit)]
+	else:
+		target = Path(path).resolve()
+		start = target if target.is_dir() else target.parent
+		candidates = [parent / "pyproject.toml" for parent in [start, *start.parents]]
+	for candidate in candidates:
+		if not candidate.is_file():
+			if explicit is not None: raise ConfigurationError(f"Configuration does not exist: {candidate}")
+			continue
+		try:
+			with candidate.open("rb") as stream: document = tomllib.load(stream)
+		except (tomllib.TOMLDecodeError, UnicodeError) as exc:
+			raise ConfigurationError(f"{candidate}: {exc}") from exc
+		section = document.get("tool", {}).get("vikela")
+		if section is None and explicit is None: continue
+		if section is None: return set()
+		if not isinstance(section, dict) or set(section) - {"disable"}:
+			raise ConfigurationError(f"{candidate}: tool.vikela supports only 'disable'")
+		value = section.get("disable", [])
+		if not isinstance(value, list) or any(rule not in {"RAI011", "RAI012"} for rule in value):
+			raise ConfigurationError(f"{candidate}: disable must be an array of RAI011/RAI012 rule IDs")
+		return set(value)
+	return set()

vikela/notebook.py

@@ -0,0 +1,11 @@
+"""IPython extension: %%vikela checks a cell, but never executes its contents."""
+import shlex
+from .analysis import analyze
+from .cli import parser, render, UsageError
+
+
+def cell_magic(line, cell):
+	args = parser().parse_args(shlex.split(line))
+	if args.paths: raise UsageError("%%vikela accepts options, not file paths")
+	findings = [f for f in analyze(cell, "<vikela-cell>") if f.rule not in args.disable]
+	render(findings, args.json, nologo=True, fix=args.fix)

vikela/pylint_plugin.py

@@ -0,0 +1,24 @@
+"""Pylint adapter: framework analysis is shared with the standalone CLI."""
+from pylint.checkers import BaseChecker
+from .analysis import analyze
+from .config import disabled_rules
+
+
+class MutationChecker(BaseChecker):
+	name = "vikela"
+	msgs = {
+		"W9011": ("RAI011: %s Suggestion: %s %s", "vikela-full-snapshot-write", "Unsafe detached projection, cross-owner live handle or retired lifetime write."),
+		"W9012": ("RAI012: %s Suggestion: %s %s", "vikela-protected-attribute", "JsonPit lifecycle metadata is engine-owned."),
+	}
+
+	def visit_module(self, node):
+		with node.stream() as stream:
+			raw = stream.read()
+		source = raw.decode(getattr(node, "file_encoding", None) or "utf-8") if isinstance(raw, bytes) else raw
+		source = source.removeprefix("\ufeff")
+		ignored = disabled_rules(node.file or ".")
+		for finding in analyze(source, node.file or "<module>"):
+			if finding.rule in ignored: continue
+			self.add_message("W9011" if finding.rule == "RAI011" else "W9012",
+				node=node, line=finding.line, col_offset=finding.column - 1,
+				args=(finding.reason, finding.suggestion, finding.documentation))

vikela/style.py

@@ -0,0 +1,110 @@
+"""CR077 terminal rendering, based on RAIkeep's shared cli-style contract."""
+from __future__ import annotations
+import os
+import platform
+import re
+import sys
+import unicodedata
+from . import __version__
+
+_SWITCH = re.compile(r"(?<![\w/\-])--?[A-Za-z][A-Za-z0-9-]*")
+
+
+def enabled(stream=None):
+	stream = sys.stdout if stream is None else stream
+	return stream.isatty() and not os.environ.get("NO_COLOR") and os.environ.get("TERM") != "dumb"
+
+
+def paint(text, color, enabled):
+	return f"\033[{color}m{text}\033[0m" if enabled else text
+
+
+def syntax(text: str, base_color: str = "36", enabled: bool = True) -> str:
+	if not enabled or not text:
+		return text
+	colors = [base_color] * len(text)
+	italic = [False] * len(text)
+	groups: list[tuple[int, int, str, bool]] = []
+	opened: list[tuple[int, str]] = []
+	quote = -1
+	for i, ch in enumerate(text):
+		if ch == "'":
+			if quote < 0:
+				quote = i
+			else:
+				colors[quote + 1:i] = ["33"] * (i - quote - 1)
+				quote = -1
+		if ch in "<([":
+			opened.append((i, ch))
+		elif ch in ">)]":
+			expected = {">": "<", ")": "(", "]": "["}[ch]
+			if opened and opened[-1][1] == expected:
+				start, kind = opened.pop()
+				depth = 0
+				choice = False
+				if kind == "(":
+					for inner in text[start + 1:i]:
+						if inner in "<([": depth += 1
+						elif inner in ">)]": depth -= 1
+						elif inner == "|" and depth == 0: choice = True
+				groups.append((start, i, kind, choice))
+	for start, end, kind, choice in sorted(groups, key=lambda g: g[1] - g[0], reverse=True):
+		if kind == "<":
+			in_choice = any(c and a < start and b > end for a, b, _, c in groups)
+			colors[start + 1:end] = ["35" if in_choice else "96"] * (end - start - 1)
+			italic[start + 1:end] = [True] * (end - start - 1)
+		elif kind == "[" or choice:
+			colors[start:end + 1] = ["35" if choice else "94"] * (end - start + 1)
+	for i, ch in enumerate(text):
+		if ch in "<>|":
+			colors[i], italic[i] = base_color, False
+	for match in _SWITCH.finditer(text):
+		colors[match.start():match.end()] = ["32"] * len(match.group())
+	result: list[str] = []
+	start = 0
+	while start < len(text):
+		end = start + 1
+		while end < len(text) and colors[end] == colors[start] and italic[end] == italic[start]: end += 1
+		result.append(paint(text[start:end], colors[start] + (";3" if italic[start] else ""), True))
+		start = end
+	return "".join(result)
+
+
+
+def width(text):
+	cells = 0; previous = 0
+	for character in text:
+		if character == "\ufe0f":
+			# Emoji presentation widens a text-default symbol such as the shield.
+			if previous == 1: cells += 1
+			continue
+		if unicodedata.combining(character) or character == "\u200d": continue
+		previous = 2 if unicodedata.east_asian_width(character) in {"W", "F"} else 1
+		cells += previous
+	return cells
+
+
+def banner(color):
+	heading = f"🛡️ Vikela Python Mutation Guardrails (vikela v{__version__}) on {platform.node()}"
+	rule = " " + "─" * max(0, width(heading) - 2)
+	return "\n".join([paint(rule, "36", color), paint(heading, "1;36", color), paint(rule, "36", color)])
+
+
+def help_text():
+	color = enabled()
+	rows = [
+		("-h, --help", "", "32", "print options and examples"),
+		("-v, --version", "", "36", "print version information"),
+		("-n, --nologo", "", "95", "do not display the banner"),
+		("--json", "", "38;5;117", "write pure JSON findings to stdout"),
+		("--fix, --qondisa", "", "38;5;208", "apply only proven safe fixes; unavailable fixes remain suggestions"),
+		("--config <file>", "", "35", "read shared [tool.vikela] project configuration"),
+		("--disable <rule>", "🛡️", "38;5;75", "disable RAI011 or RAI012 (repeatable)"),
+	]
+	result = [banner(color), syntax("Usage: vikela <file.py|notebook.ipynb|directory> [--json] [--fix|--qondisa]", enabled=color), ""]
+	label_width = max(len(row[0]) for row in rows)
+	for label, glyph, base, description in rows:
+		result.append(syntax(label.ljust(label_width), base, color) + "  " + paint(glyph, base, color) + " " * (4 - width(glyph)) + syntax(description, base, color))
+	result.extend(["", "Exit codes: 0 clean, 1 findings, 2 syntax/configuration, 4 internal/environment failure.",
+		"Checks never execute the inspected code. JSON and notebook checks never add a banner."])
+	return "\n".join(result)

vikela-4.6.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: vikela
+Version: 4.6.0
+Summary: Python mutation guardrails for JsonPit
+Project-URL: Repository, https://github.com/Burkhardt/vikela
+Project-URL: Documentation, https://github.com/Burkhardt/vikela/blob/main/docs/rules.md
+Author: Dr. Rainer Burkhardt
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: ipython>=8; extra == 'dev'
+Requires-Dist: pylint<5,>=3.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: notebook
+Requires-Dist: ipython>=8; extra == 'notebook'
+Provides-Extra: pylint
+Requires-Dist: pylint<5,>=3.3; extra == 'pylint'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Burkhardt/vikela/main/assets/vikela-logo.svg" width="160" height="160" alt="Vikela Logo" />
+</p>
+
+<h1 align="center">Vikela 🛡️</h1>
+
+<p align="center">
+  <strong>Python mutation guardrails and AST linter for JsonPit.</strong><br>
+  <em>The defensive shield protecting distributed state from concurrent cloud replica stomps.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/vikela/"><img src="https://img.shields.io/badge/PyPI-vikela-D4AF37?style=flat-square&logo=pypi" alt="PyPI"></a>
+  <a href="https://github.com/Burkhardt/RAIkeep/blob/main/doc/CR077_AIA_and_AfricaStage_to_RAIkeep_Vikela_and_JsonPit_Mutation_Guardrails.md"><img src="https://img.shields.io/badge/CR-CR077-blue?style=flat-square" alt="Specification"></a>
+  <a href="docs/VIKELA_VISUAL_IDENTITY_AND_ICON_SPEC.md"><img src="https://img.shields.io/badge/Identity-Modernist%20Ihawu-AA8214?style=flat-square" alt="Design Spec"></a>
+</p>
+
+---
+
+## Overview
+
+**Vikela** (*isiZulu: "to protect / shield"*) provides static analysis and mutation guardrails for `JsonPit` and its surrounding framework across the fleet. It functions both as a standalone CLI (`vikela`) and as a native Pylint checker plugin (`pylint --load-plugins=vikela`).
+
+### The Twin-Shield Doctrine
+* **C# development (.NET):** Checked by `RaiGuard`.
+* **Python development:** Checked by `vikela`; JsonPit itself enforces runtime mutation guards.
+* **The Straightening Action (`--qondisa`):** An official first-class alias for `--fix` (*isiZulu: "to straighten out / rectify"*), reserved for proven safe repairs. Version 4.6.0 provides suggestions and has no approved automatic rewrites.
+
+---
+
+## Core Rules
+
+| Rule ID | Diagnostic Symbol | Description |
+| :--- | :--- | :--- |
+| **`RAI011`** | `vikela-full-snapshot-write` | Prevents full-snapshot read-modify-writes that erase concurrent cloud replica fields. |
+| **`RAI012`** | `vikela-protected-attribute` | Protects immutable lifecycle and schema attributes from unauthorized client modification. |
+
+---
+
+## Terminal & CLI Experience
+
+```bash
+# Standard Scan
+󰞀 vikela .
+
+# Request safe fixes (v4.6.0 reports suggestions and leaves source unchanged)
+vikela src/ --qondisa
+
+# Pure JSON for CI/CD audit pipelines
+vikela src/ --json
+```
+
+---
+
+## IDE & Editor Integration
+
+### VS Code
+Configure in `.vscode/settings.json`:
+```json
+{
+  "pylint.args": [
+    "--load-plugins=vikela"
+  ]
+}
+```
+
+### JupyterLab
+```python
+%load_ext vikela
+
+%%vikela
+# Checks this cell WITHOUT executing it
+```
+
+---
+
+## Visual Identity & Heraldry
+Vikela's emblem is the **Modernist Ihawu**—drawing from the elliptical geometry of the traditional Nguni shield, anchored by the central **Qondisa Axis** (the plumb line that straightens crooked code).
+
+* **Design Specification:** [`docs/VIKELA_VISUAL_IDENTITY_AND_ICON_SPEC.md`](docs/VIKELA_VISUAL_IDENTITY_AND_ICON_SPEC.md)
+* **Master Vector:** [`assets/logo.svg`](assets/logo.svg)
+* **Curator:** Koyo (Chief Marketing & Web Design Assistant)
+
+
+## Version 4.6.0 installation and contracts
+
+Vikela is optional development tooling alongside RAIkeep 4.6.0. Neither jsonpit nor
+jpit depends on it. Until publication, install from this checkout in a development
+virtual environment:
+
+```sh
+python -m pip install -e '.[dev]'
+python -m pytest
+vikela -v
+```
+
+After publication, install `vikela==4.6.0` for the independent CLI, or
+`vikela[pylint]==4.6.0` inside the project's interpreter for editor checks.
+`vikela[notebook]==4.6.0` adds IPython support in the chosen kernel interpreter.
+A global CLI environment alone does not expose the checker in another venv.
+
+Exit codes: **0** clean; **1** findings; **2** syntax/configuration;
+**4** internal/environment failure. Pylint retains its own native exit codes.
+`--json` emits a pure array; operational errors go to stderr. Scans do not import
+or execute the inspected application. `--fix` and `--qondisa` are exact aliases;
+no speculative field-dropping rewrite is available in 4.6.0.
+
+- [Rules, shared project configuration and analysis limits](docs/rules.md)
+- [VS Code, PyCharm and JupyterLab setup](docs/editors.md)
+
+The CLI and plugin share `[tool.vikela]` configuration in pyproject.toml, with a
+`disable` array of logical rule IDs. Checks are bounded and conservative: no
+findings does not prove arbitrary dynamic code safe. Notebook scans follow
+source-cell document order, not previous kernel execution order.
+
+Publication/provisioning is orchestrated by Engenho; production server nodes do
+not receive development lint tooling by default. Native PyCharm inspections are
+milestone 2; milestone 1 supplies an External Tool configuration.

vikela-4.6.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vikela/__init__.py,sha256=RHuOX-acH6_MeUZu18ZAeP7au-OEzXu0stQkrgFJKWQ,557
+vikela/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+vikela/analysis.py,sha256=GBgKgKVWVDaq0q6B8KWMp4p4s0gNrewnbe2TM6zJL0I,16381
+vikela/cli.py,sha256=xej58eMzs793nPh_6dNZv9aeDCsd_vqNAz3De90WztQ,5023
+vikela/config.py,sha256=a7rYEIDNsRv30tS5OGq9X4RvCxZ4Hl6W3XqKP4FBIsI,1362
+vikela/notebook.py,sha256=nhquCbM97WxyYBHiWhQiUw-p8dNdL9IIzwaD3c6kPzk,465
+vikela/pylint_plugin.py,sha256=wJi4SGxnGN5QNwGnNbj6eL83NXF01JXJv_dwi4U1oGw,1111
+vikela/style.py,sha256=bMAq6-Zins5yJhTOlQKId3WAapiMwlsM4kQyi3jJtw4,4234
+vikela-4.6.0.dist-info/METADATA,sha256=6Q2mjo6dKNigqgzTfSe_42s3TeBCV-9dOJmp2iAmTS0,5445
+vikela-4.6.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+vikela-4.6.0.dist-info/entry_points.txt,sha256=Y6TEu9LRqD0bsm-2rxs_B_2f6VPV7Fp3_Rg8HSMPWto,43
+vikela-4.6.0.dist-info/licenses/LICENSE,sha256=44MnwGRgJIs4OmuNbHs7OvGgwlf_nj-d7DK9PRTtddM,9155
+vikela-4.6.0.dist-info/RECORD,,

vikela-4.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vikela-4.6.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vikela = vikela.cli:main

vikela-4.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS