AssayFluxScientificSystems 0.1.0__py3-none-any.whl

assayflux/__init__.py

@@ -0,0 +1,6 @@
+"""AssayFlux Scientific Systems: language runtime and developer tools."""
+__title__ = "AssayFlux Scientific Systems"
+__version__ = "0.1.0"
+__author__ = "Md Safarujjaman"
+__email__ = "assayflux@gmail.com"
+__url__ = "https://www.assayflux.com"

assayflux/__main__.py

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

assayflux/cli.py

@@ -0,0 +1,268 @@
+"""Command line interface for validation, interpretation, health and local reports."""
+from __future__ import annotations
+import argparse, json, sys, traceback
+from pathlib import Path
+from assayflux import __version__
+from assayflux.diagnostics.model import AssayFluxError, SourceLocation, Diagnostic, Severity
+from assayflux.diagnostics.reporter import write_report, read_reports
+from assayflux.security.checkpoints import SecurityPolicy, read_source
+from assayflux.language.parser import parse
+from assayflux.language.semantic import check
+from assayflux.runtime.interpreter import Interpreter
+from assayflux.runtime.native_build import build_cpp
+from assayflux.developer.doctor import run_doctor
+
+def _load(path: Path, policy: SecurityPolicy):
+    source = read_source(path, policy)
+    program = parse(source, str(path.resolve()))
+    check(program)
+    return source, program
+
+def _diagnostic(exc: AssayFluxError, report: bool = True):
+    d = exc.diagnostic()
+    loc = d.location
+    print(f"{d.severity.value.upper()} {d.code}: {d.message}", file=sys.stderr)
+    print(f"  --> {loc.file}:{loc.line}:{loc.column}", file=sys.stderr)
+    if d.details: print(f"  details: {d.details}", file=sys.stderr)
+    if d.suggestion: print(f"  help: {d.suggestion}", file=sys.stderr)
+    if report:
+        try: print(f"  report: {write_report(d)}", file=sys.stderr)
+        except OSError: print("  warning: could not persist local diagnostic report", file=sys.stderr)
+
+def _unexpected(exc: Exception, source: str = "<cli>") -> int:
+    # Save frame metadata only; do not copy source lines, environment variables, or locals.
+    frames = traceback.extract_tb(exc.__traceback__)
+    safe_stack = tuple(f"{Path(frame.filename).name}:{frame.lineno} in {frame.name}" for frame in frames[-12:])
+    d = Diagnostic("AF-INTERNAL-UNEXPECTED", "internal", Severity.ERROR,
+                   "Unexpected internal failure; please inspect the local report", SourceLocation(Path(source).name),
+                   cause_type=type(exc).__name__, stack=safe_stack)
+    try: print(f"ERROR {d.code}: {d.message}\n  report: {write_report(d)}", file=sys.stderr)
+    except OSError: print(f"ERROR {d.code}: {d.message}", file=sys.stderr)
+    return 2
+
+def cmd_check(args):
+    policy = SecurityPolicy(max_source_bytes=args.max_source_bytes)
+    try: _load(Path(args.file), policy)
+    except AssayFluxError as exc: _diagnostic(exc); return 1
+    print(f"OK: {args.file} passed source, syntax, AST, and semantic checks")
+    return 0
+
+def cmd_run(args):
+    modules = tuple(x.strip() for x in args.python_modules.split(",") if x.strip()) if args.allow_python else ()
+    allowed = {"math", "statistics", "json", "numpy", "pandas", "scipy.stats"}
+    if any(m not in allowed for m in modules):
+        print("ERROR: Python bridge currently supports only: math,statistics,json,numpy,pandas,scipy.stats", file=sys.stderr); return 2
+    grants = tuple(["python.call"] + [f"python.module:{m}" for m in modules]) if modules else ()
+    policy = SecurityPolicy(max_source_bytes=args.max_source_bytes, max_steps=args.max_steps,
+                            max_loop_iterations=args.max_loop_iterations, max_output_chars=args.max_output_chars,
+                            capabilities=grants, allowed_python_modules=modules or ("math", "statistics", "json"))
+    try:
+        _, program = _load(Path(args.file), policy)
+        result = Interpreter(policy).run(program)
+        for line in result.output: print(line)
+        if args.stats: print(f"[AssayFlux] steps={result.steps} variables={len(result.variables)}", file=sys.stderr)
+        return 0
+    except AssayFluxError as exc: _diagnostic(exc); return 1
+    except Exception as exc: return _unexpected(exc, str(args.file))
+
+def cmd_build(args):
+    try:
+        result = build_cpp(args.source, args.output, workspace=args.workspace, compiler=args.compiler, timeout=args.timeout, capabilities={"native.build"})
+        print(f"Built {result.output} with {result.compiler} in {result.duration_seconds:.2f}s")
+        if result.warnings.strip(): print(result.warnings.rstrip(), file=sys.stderr)
+        return 0
+    except AssayFluxError as exc:
+        _diagnostic(exc); return 1
+    except Exception as exc: return _unexpected(exc, str(args.source))
+
+def cmd_doctor(args):
+    checks = run_doctor(); failed = False
+    print(f"AssayFlux Doctor {__version__}\n")
+    for c in checks:
+        print(f"[{c.status}] {c.name}: {c.detail}")
+        if c.required and c.status != "PASS": failed = True
+    print("\nStatus:", "FAILED REQUIRED CHECKS" if failed else "READY (optional tools may be missing)")
+    return 1 if failed else 0
+
+def cmd_reports(args):
+    rows = read_reports()
+    if args.report_action == "list":
+        if not rows: print("No local diagnostic reports found.")
+        for i, row in enumerate(rows, 1): print(f"{i}. {row.get('timestamp','?')} {row.get('code','?')} {row.get('message','')}")
+        return 0
+    if args.report_action == "show":
+        if args.index < 1 or args.index > len(rows): print("Report index out of range", file=sys.stderr); return 2
+        print(json.dumps(rows[args.index-1], indent=2, ensure_ascii=False)); return 0
+    if args.report_action == "export":
+        dest = Path(args.path)
+        try: dest.write_text(json.dumps(rows, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        except OSError as exc: print(f"Could not export reports: {type(exc).__name__}", file=sys.stderr); return 1
+        print(f"Exported {len(rows)} report(s) to {dest}"); return 0
+    return 2
+
+def cmd_setup(args):
+    import subprocess
+    extras = []
+    if args.science: extras.append("science")
+    if args.dev: extras.append("dev")
+    if not extras:
+        print("Core Python dependencies are installed automatically by pip. Choose --science to install NumPy/SciPy/pandas/Matplotlib, or --dev for test/build tools.")
+        print("External tools such as JDK, Android SDK, Gradle bootstrap, and g++ are platform-specific; run 'assayflux doctor' to inspect them.")
+        return 0
+    spec = "AssayFluxScientificSystems[" + ",".join(extras) + "]==" + __version__
+    try:
+        proc = subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", spec], check=False, timeout=args.timeout)
+    except subprocess.TimeoutExpired:
+        print("Optional dependency installation timed out", file=sys.stderr); return 124
+    except OSError as exc:
+        print(f"Could not start pip: {type(exc).__name__}", file=sys.stderr); return 1
+    if proc.returncode == 0: print("Optional Python extras installed. Run 'assayflux doctor' to recheck the environment.")
+    else: print("Optional extras installation failed; check network access, package publication, and pip output.", file=sys.stderr)
+    return proc.returncode
+
+def cmd_syntax(args):
+    catalog = {
+      "variables": ["let name = value — declare a variable once", "name = value — assign an existing variable", "Strings use single or double quotes; numbers are integers or decimals."],
+      "types": ["Built-in values: number, string, boolean (true/false), null.", "Collections and user-defined functions are not implemented in the current core grammar."],
+      "operators": ["Arithmetic: + - * / %", "Comparisons: == != < > <= >=", "Unary: -value, not boolean", "Conditions must evaluate to true or false."],
+      "control": ['app "Application name" — optional declaration', "print(expression) — write one output line", "if condition { ... } else { ... }", "while condition { ... }", "Statements can be separated by a newline or semicolon."],
+      "python": ['pycall("math", "sqrt", 81) — call an approved Python function', "Run with: assayflux run file.assayflux --allow-python --python-modules math", "Supported bridge modules: math, statistics, json, and optional numpy, pandas, and scipy.stats. Calls are explicitly allowlisted; this is not a sandbox."],
+      "security": ["Default execution denies Python bridge capabilities.", "Source, step, loop, output, numeric and AST limits are applied.", "Never treat in-process language controls as an OS sandbox; don't execute untrusted native code."],
+    }
+    keys = catalog if args.topic == "all" else {args.topic: catalog[args.topic]}
+    print("AssayFlux Language Syntax Reference 0.1.0")
+    for topic, entries in keys.items():
+        print(f"\n[{topic.upper()}]")
+        for entry in entries: print(f"  • {entry}")
+    if args.topic == "all":
+        print("\n[EXAMPLE]")
+        print('  app "Scientific demo"\n  let value = 6 * 7\n  print(value)\n  print(pycall("math", "sqrt", 81))')
+    return 0
+
+def cmd_project_create(args):
+    dest = Path(args.path).expanduser().resolve()
+    try:
+        dest.mkdir(parents=True, exist_ok=True)
+        import json as _json
+        safe_app_name = _json.dumps(args.name, ensure_ascii=False)
+        (dest / "main.assayflux").write_text(f'app {safe_app_name}\nlet answer = 6 * 7\nprint(answer)\n', encoding="utf-8")
+        (dest / "README.md").write_text(f"# {args.name}\n\nCreated with AssayFlux Scientific Systems 0.1.0.\n\nRun: `assayflux run main.assayflux`\n", encoding="utf-8")
+    except OSError as exc:
+        print(f"Could not create project: {type(exc).__name__}", file=sys.stderr); return 1
+    print(f"Created starter project at {dest}"); return 0
+
+def cmd_os(args):
+    if args.action == "roadmap":
+        print("AssayFluxOS roadmap: host CLI/workspace prototype → Linux-based development environment → customized distribution → research toward an independent kernel.")
+    else:
+        print("AssayFluxOS tools are a host-side development prototype bundled with AssayFlux Scientific Systems.")
+        print("This command does not boot a separate OS or provide a kernel/distribution.")
+    return 0
+
+def cmd_android_wrapper(args):
+    import shutil, subprocess
+    project = Path(args.project).expanduser().resolve()
+    if not project.is_dir(): print("Android project directory not found", file=sys.stderr); return 2
+    gradle = shutil.which("gradle")
+    if not gradle:
+        print("Gradle is required once to generate the wrapper. Install Gradle, then rerun this command.", file=sys.stderr)
+        print("After generation, gradlew downloads the configured Gradle distribution on first use.", file=sys.stderr)
+        return 2
+    try:
+        proc = subprocess.run([gradle, "wrapper", f"--gradle-version={args.gradle_version}"], cwd=project,
+                              capture_output=True, text=True, timeout=180, check=False)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        print(f"Gradle wrapper generation failed: {type(exc).__name__}", file=sys.stderr); return 1
+    if proc.returncode:
+        print((proc.stderr or proc.stdout)[-4000:], file=sys.stderr); return proc.returncode
+    print(f"Gradle wrapper generated in {project}. Review and commit gradlew, gradlew.bat and gradle/wrapper/.")
+    return 0
+
+def cmd_android_build(args):
+    import os, subprocess
+    project = Path(args.project).expanduser().resolve()
+    wrapper = project / ("gradlew.bat" if os.name == "nt" else "gradlew")
+    if not project.is_dir(): print("Android project directory not found", file=sys.stderr); return 2
+    if not wrapper.is_file():
+        print("Gradle wrapper is missing. Generate it first: assayflux android wrapper PROJECT --gradle-version 8.9", file=sys.stderr)
+        return 2
+    if not (os.environ.get("ANDROID_HOME") or os.environ.get("ANDROID_SDK_ROOT")):
+        print("Warning: ANDROID_HOME/ANDROID_SDK_ROOT is not set; Gradle may still find an SDK from local configuration.", file=sys.stderr)
+    if os.name != "nt":
+        try: wrapper.chmod(wrapper.stat().st_mode | 0o111)
+        except OSError: pass
+    task = ("bundle" if args.bundle else "assemble") + args.variant.title()
+    command = [str(wrapper), task]
+    try:
+        proc = subprocess.run(command, cwd=project, capture_output=True, text=True, timeout=args.timeout, check=False)
+    except subprocess.TimeoutExpired:
+        print(f"Android build timed out after {args.timeout} seconds", file=sys.stderr); return 124
+    except OSError as exc:
+        print(f"Could not start Gradle wrapper: {type(exc).__name__}", file=sys.stderr); return 1
+    if proc.stdout: print(proc.stdout[-12000:])
+    if proc.stderr: print(proc.stderr[-8000:], file=sys.stderr)
+    if proc.returncode:
+        print(f"Android build failed (exit {proc.returncode}). Check JDK, Android SDK/licenses, plugin compatibility, and project sources.", file=sys.stderr)
+        return proc.returncode
+    print(f"Android Gradle task completed: {task}. Check the project's build/outputs directory for APK/AAB artifacts.")
+    return 0
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="assayflux", description="AssayFlux language and secure development tools")
+    p.add_argument("--version", action="version", version=f"AssayFlux {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+    check_p = sub.add_parser("check", help="validate source without executing it")
+    check_p.add_argument("file"); check_p.add_argument("--max-source-bytes", type=int, default=1_000_000); check_p.set_defaults(func=cmd_check)
+    run_p = sub.add_parser("run", help="validate and interpret a source file")
+    run_p.add_argument("file"); run_p.add_argument("--max-source-bytes", type=int, default=1_000_000)
+    run_p.add_argument("--max-steps", type=int, default=100_000); run_p.add_argument("--max-loop-iterations", type=int, default=10_000)
+    run_p.add_argument("--max-output-chars", type=int, default=1_000_000); run_p.add_argument("--stats", action="store_true")
+    run_p.add_argument("--allow-python", action="store_true", help="grant explicit access to approved Python bridge modules")
+    run_p.add_argument("--python-modules", default="math,statistics,json", help="comma-separated allowlist used with --allow-python")
+    run_p.set_defaults(func=cmd_run)
+    build = sub.add_parser("build", help="compile trusted generated C++ source; does not execute it")
+    build.add_argument("source"); build.add_argument("--output", default="build/assayflux-native")
+    build.add_argument("--workspace", default="."); build.add_argument("--compiler", choices=("g++", "clang++"), default="g++")
+    build.add_argument("--timeout", type=float, default=30.0); build.set_defaults(func=cmd_build)
+    doc = sub.add_parser("doctor", help="check development environment health"); doc.set_defaults(func=cmd_doctor)
+    reports = sub.add_parser("report", help="inspect local diagnostic reports"); rs = reports.add_subparsers(dest="report_action", required=True)
+    rs.add_parser("list")
+    show = rs.add_parser("show"); show.add_argument("index", type=int)
+    export = rs.add_parser("export"); export.add_argument("path")
+    reports.set_defaults(func=cmd_reports)
+    setup = sub.add_parser("setup", help="install optional Python helper dependencies")
+    setup.add_argument("--science", action="store_true", help="install NumPy, SciPy, pandas, and Matplotlib")
+    setup.add_argument("--dev", action="store_true", help="install pytest, build, ruff, and twine")
+    setup.add_argument("--timeout", type=float, default=900)
+    setup.set_defaults(func=cmd_setup)
+    syntax = sub.add_parser("syntax", help="show built-in language syntax, rules, and examples")
+    syntax.add_argument("topic", nargs="?", default="all", choices=("all", "variables", "types", "operators", "control", "python", "security"))
+    syntax.set_defaults(func=cmd_syntax)
+    project = sub.add_parser("project", help="project builder utilities")
+    ps = project.add_subparsers(dest="project_action", required=True)
+    create = ps.add_parser("create", help="create a starter AssayFlux project")
+    create.add_argument("path", nargs="?", default="."); create.add_argument("--name", default="MyAssayFluxProject")
+    create.set_defaults(func=cmd_project_create)
+    os_cmd = sub.add_parser("os", help="AssayFluxOS development utilities (not a standalone OS)")
+    os_cmd.add_argument("action", nargs="?", default="info", choices=("info", "roadmap")); os_cmd.set_defaults(func=cmd_os)
+    android = sub.add_parser("android", help="Android APK/AAB build helpers using Gradle")
+    android_sub = android.add_subparsers(dest="android_action", required=True)
+    wrapper = android_sub.add_parser("wrapper", help="generate Gradle wrapper files")
+    wrapper.add_argument("project", nargs="?", default="."); wrapper.add_argument("--gradle-version", default="8.9")
+    wrapper.set_defaults(func=cmd_android_wrapper)
+    android_build = android_sub.add_parser("build", help="run assembleDebug or bundleRelease with the project wrapper")
+    android_build.add_argument("project", nargs="?", default=".")
+    android_build.add_argument("--variant", choices=("debug", "release"), default="debug")
+    android_build.add_argument("--bundle", action="store_true", help="build an Android App Bundle (AAB) instead of APK")
+    android_build.add_argument("--timeout", type=float, default=1800)
+    android_build.set_defaults(func=cmd_android_build)
+    return p
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try: return args.func(args)
+    except KeyboardInterrupt: print("Interrupted", file=sys.stderr); return 130
+    except AssayFluxError as exc: _diagnostic(exc); return 1
+    except Exception as exc: return _unexpected(exc, getattr(args, "file", getattr(args, "source", "<cli>")))
+
+if __name__ == "__main__": raise SystemExit(main())

assayflux/developer/__init__.py

@@ -0,0 +1 @@
+from .doctor import run_doctor

assayflux/developer/doctor.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+import importlib.util, platform, shutil, sys
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    status: str
+    detail: str
+    required: bool = False
+
+def run_doctor() -> list[Check]:
+    checks = [Check("Python", "PASS" if sys.version_info >= (3,11) else "FAIL", platform.python_version(), True),
+              Check("Lark parser", "PASS" if importlib.util.find_spec("lark") else "FAIL", "lark package", True),
+              Check("SQLite", "PASS" if importlib.util.find_spec("sqlite3") else "FAIL", "Python sqlite3 module", True)]
+    for tool in ("g++", "clang++", "node", "git", "java", "gradle", "adb"):
+        path = shutil.which(tool); checks.append(Check(tool, "AVAILABLE" if path else "OPTIONAL-MISSING", path or "not found"))
+    checks.append(Check("Android SDK", "AVAILABLE" if (__import__("os").environ.get("ANDROID_HOME") or __import__("os").environ.get("ANDROID_SDK_ROOT")) else "OPTIONAL-MISSING", "ANDROID_HOME/ANDROID_SDK_ROOT"))
+    return checks

assayflux/diagnostics/__init__.py

@@ -0,0 +1,2 @@
+from .model import *
+from .reporter import write_report, read_reports

assayflux/diagnostics/model.py

@@ -0,0 +1,61 @@
+"""Stable diagnostic model shared by compiler stages and runtime."""
+from __future__ import annotations
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from enum import StrEnum
+from typing import Any
+
+class Severity(StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    HINT = "hint"
+
+@dataclass(frozen=True, slots=True)
+class SourceLocation:
+    file: str = "<memory>"
+    line: int = 1
+    column: int = 1
+    end_line: int | None = None
+    end_column: int | None = None
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    code: str
+    category: str
+    severity: Severity
+    message: str
+    location: SourceLocation = field(default_factory=SourceLocation)
+    details: str | None = None
+    suggestion: str | None = None
+    cause_type: str | None = None
+    stack: tuple[str, ...] = ()
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+class AssayFluxError(Exception):
+    code = "AF-INTERNAL-001"
+    category = "internal"
+    def __init__(self, message: str, *, location: SourceLocation | None = None,
+                 details: str | None = None, suggestion: str | None = None):
+        super().__init__(message)
+        self.message = message
+        self.location = location or SourceLocation()
+        self.details = details
+        self.suggestion = suggestion
+    def diagnostic(self) -> Diagnostic:
+        return Diagnostic(self.code, self.category, Severity.ERROR, self.message,
+                          self.location, self.details, self.suggestion, type(self).__name__)
+
+class SourceError(AssayFluxError): code = "AF-SOURCE-001"; category = "source"
+class LexError(AssayFluxError): code = "AF-LEX-001"; category = "lexical"
+class ParseError(AssayFluxError): code = "AF-PARSE-001"; category = "syntax"
+class AstError(AssayFluxError): code = "AF-AST-001"; category = "ast"
+class TypeCheckError(AssayFluxError): code = "AF-TYPE-001"; category = "type"
+class SecurityError(AssayFluxError): code = "AF-SEC-001"; category = "security"
+class RuntimeErrorAF(AssayFluxError): code = "AF-RUNTIME-001"; category = "runtime"
+class ImportErrorAF(AssayFluxError): code = "AF-IMPORT-001"; category = "import"
+class PythonBridgeError(AssayFluxError): code = "AF-PYTHON-001"; category = "python-interop"
+class DatabaseErrorAF(AssayFluxError): code = "AF-SQL-001"; category = "database"
+class BuildError(AssayFluxError): code = "AF-BUILD-001"; category = "build"

assayflux/diagnostics/reporter.py

@@ -0,0 +1,60 @@
+"""Local-first structured bug/diagnostic reporting; never uploads automatically."""
+from __future__ import annotations
+import json, os, tempfile
+from pathlib import Path
+from typing import Iterable
+from .model import Diagnostic
+
+DEFAULT_REPORT_DIR = Path(os.environ.get("ASSAYFLUX_REPORT_DIR", Path.home() / ".assayflux" / "reports"))
+MAX_REPORT_BYTES = 10 * 1024 * 1024
+MAX_REPORTS = 20_000
+
+def _private_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try: path.chmod(0o700)
+    except OSError: pass
+
+def write_report(diagnostic: Diagnostic, report_dir: Path | None = None) -> Path:
+    """Atomically append a minimized JSONL report. Source contents are never captured."""
+    root = report_dir or DEFAULT_REPORT_DIR
+    _private_dir(root)
+    target = root / "diagnostics.jsonl"
+    rotated = root / "diagnostics.previous.jsonl"
+    try:
+        if target.stat().st_size >= MAX_REPORT_BYTES:
+            try: rotated.unlink()
+            except FileNotFoundError: pass
+            os.replace(target, rotated)
+            try: rotated.chmod(0o600)
+            except OSError: pass
+    except FileNotFoundError: pass
+    record = json.dumps(diagnostic.to_dict(), ensure_ascii=False, sort_keys=True)
+    # Use a single O_APPEND write to reduce interleaving between cooperating processes.
+    fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+    try:
+        os.write(fd, (record + "\n").encode("utf-8"))
+    finally: os.close(fd)
+    try: target.chmod(0o600)
+    except OSError: pass
+    return target
+
+def read_reports(report_dir: Path | None = None) -> list[dict]:
+    root = report_dir or DEFAULT_REPORT_DIR
+    rows: list[dict] = []
+    for path in (root / "diagnostics.previous.jsonl", root / "diagnostics.jsonl"):
+        if not path.exists(): continue
+        try:
+            size = path.stat().st_size
+            with path.open("rb") as stream:
+                if size > MAX_REPORT_BYTES: stream.seek(size - MAX_REPORT_BYTES)
+                raw = stream.read(MAX_REPORT_BYTES + 1)
+            text = raw.decode("utf-8", errors="replace")
+            if size > MAX_REPORT_BYTES: text = text.split("\n", 1)[-1]
+        except OSError:
+            continue
+        for line_no, line in enumerate(text.splitlines(), 1):
+            if len(rows) >= MAX_REPORTS: return rows
+            try: rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                rows.append({"code":"AF-REPORT-CORRUPT", "line":line_no, "message":"Malformed report entry"})
+    return rows

assayflux/language/ast_nodes.py

@@ -0,0 +1,36 @@
+"""Small immutable AST. All source locations are preserved for diagnostics."""
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+from assayflux.diagnostics.model import SourceLocation
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    loc: SourceLocation
+@dataclass(frozen=True, slots=True)
+class Program(Node): statements: tuple[Node, ...]
+@dataclass(frozen=True, slots=True)
+class AppDecl(Node): name: str
+@dataclass(frozen=True, slots=True)
+class LetDecl(Node): name: str; value: Node
+@dataclass(frozen=True, slots=True)
+class Assign(Node): name: str; value: Node
+@dataclass(frozen=True, slots=True)
+class Print(Node): value: Node | None
+@dataclass(frozen=True, slots=True)
+class If(Node): condition: Node; then_body: tuple[Node, ...]; else_body: tuple[Node, ...]
+@dataclass(frozen=True, slots=True)
+class While(Node): condition: Node; body: tuple[Node, ...]
+@dataclass(frozen=True, slots=True)
+class ExprStmt(Node): value: Node
+@dataclass(frozen=True, slots=True)
+class Literal(Node): value: Any
+@dataclass(frozen=True, slots=True)
+class Variable(Node): name: str
+@dataclass(frozen=True, slots=True)
+class Unary(Node): op: str; value: Node
+@dataclass(frozen=True, slots=True)
+class Binary(Node): left: Node; op: str; right: Node
+
+@dataclass(frozen=True, slots=True)
+class PythonCall(Node): module: str; function: str; args: tuple[Node, ...]

assayflux/language/ast_validator.py

@@ -0,0 +1,30 @@
+"""Checkpoint validator for AST shape, supported node types, and nesting depth."""
+from __future__ import annotations
+from dataclasses import fields, is_dataclass
+from assayflux.diagnostics.model import AstError
+from . import ast_nodes as A
+
+_ALLOWED = {A.Program, A.AppDecl, A.LetDecl, A.Assign, A.Print, A.If, A.While,
+            A.ExprStmt, A.Literal, A.Variable, A.Unary, A.Binary, A.PythonCall}
+_MAX_DEPTH = 512
+
+def validate_ast(root: A.Program) -> A.Program:
+    if type(root) is not A.Program: raise AstError("AST root must be a Program node")
+    seen = 0
+    def visit(node, depth):
+        nonlocal seen
+        seen += 1
+        if seen > 1_000_000: raise AstError("AST node count exceeds safety limit", location=node.loc)
+        if depth > _MAX_DEPTH: raise AstError("AST nesting depth exceeds safety limit", location=node.loc)
+        if type(node) not in _ALLOWED: raise AstError(f"Unsupported AST node type: {type(node).__name__}", location=getattr(node, "loc", None))
+        for f in fields(node):
+            value = getattr(node, f.name)
+            if isinstance(value, A.Node): visit(value, depth + 1)
+            elif isinstance(value, tuple):
+                for item in value:
+                    if isinstance(item, A.Node): visit(item, depth + 1)
+                    elif isinstance(item, tuple):
+                        for nested in item:
+                            if isinstance(nested, A.Node): visit(nested, depth + 1)
+    visit(root, 0)
+    return root

assayflux/language/grammar.lark

@@ -0,0 +1,43 @@
+// AssayFlux Scientific Systems 0.1.0 active parser grammar. Deliberately small; see docs/SYNTAX_REFERENCE.md.
+start: _NL* (statement _NL*)*
+?statement: app_decl | let_decl | assign_stmt | print_stmt | if_stmt | while_stmt | expr_stmt
+app_decl: "app" STRING
+let_decl: "let" NAME "=" expr
+assign_stmt: NAME "=" expr
+print_stmt: "print" "(" [expr] ")"
+if_stmt: "if" expr block ["else" block]
+while_stmt: "while" expr block
+block: "{" _NL* (statement _NL*)* "}"
+expr_stmt: expr
+?expr: comparison
+?comparison: sum (COMP_OP sum)*
+?sum: term (ADD_OP term)*
+?term: unary (MUL_OP unary)*
+?unary: NOT unary -> unary_expr
+      | UNARY_MINUS unary -> unary_expr
+      | atom
+?atom: pycall_expr
+     | NUMBER -> number
+     | STRING -> string
+     | TRUE -> true
+     | FALSE -> false
+     | NULL -> null
+     | NAME -> variable
+     | "(" expr ")"
+pycall_expr: "pycall" "(" STRING "," STRING ("," expr)* ")"
+ADD_OP: "+" | "-"
+MUL_OP: "*" | "/" | "%"
+COMP_OP: "==" | "!=" | "<=" | ">=" | "<" | ">"
+UNARY_MINUS.2: "-"
+NOT.2: "not"
+TRUE.2: "true"
+FALSE.2: "false"
+NULL.2: "null"
+NAME: /[A-Za-z_][A-Za-z0-9_]*/
+NUMBER: /(?:0|[1-9][0-9]*)(?:\.[0-9]+)?/
+STRING: /"([^"\\]|\\.)*"|'([^'\\]|\\.)*'/
+COMMENT: /#[^\n]*/
+_NL: /(?:\r?\n|;)+/
+%import common.WS_INLINE
+%ignore WS_INLINE
+%ignore COMMENT

assayflux/language/parser.py

@@ -0,0 +1,95 @@
+"""Lark-backed parser and AST builder. No regex-based grammar parsing."""
+from __future__ import annotations
+import ast as py_ast
+from pathlib import Path
+from lark import Lark, Transformer, Token, UnexpectedInput
+from lark.exceptions import VisitError
+from assayflux.diagnostics.model import SourceLocation, ParseError, AstError
+from . import ast_nodes as A
+from .ast_validator import validate_ast
+
+_GRAMMAR = Path(__file__).with_name("grammar.lark").read_text(encoding="utf-8")
+_PARSER = Lark(_GRAMMAR, parser="lalr", lexer="contextual", propagate_positions=True,
+               maybe_placeholders=False, start="start")
+
+def _loc(meta, filename: str) -> SourceLocation:
+    return SourceLocation(filename, getattr(meta, "line", 1) or 1,
+                          getattr(meta, "column", 1) or 1,
+                          getattr(meta, "end_line", None), getattr(meta, "end_column", None))
+
+class _BuildAST(Transformer):
+    def __init__(self, filename: str): super().__init__(); self.filename = filename
+    def start(self, items):
+        loc = SourceLocation(self.filename, 1, 1)
+        return A.Program(loc, tuple(x for x in items if isinstance(x, A.Node)))
+    def app_decl(self, items):
+        token = items[0]; return A.AppDecl(_token_loc(token, self.filename), _decode_string(str(token)))
+    def let_decl(self, items):
+        name, value = items; return A.LetDecl(_token_loc(name, self.filename), str(name), value)
+    def assign_stmt(self, items):
+        name, value = items; return A.Assign(_token_loc(name, self.filename), str(name), value)
+    def print_stmt(self, items):
+        return A.Print(_node_loc(items[0], self.filename) if items else SourceLocation(self.filename), items[0] if items else None)
+    def if_stmt(self, items):
+        condition = items[0]; blocks = [x for x in items[1:] if isinstance(x, tuple)]
+        return A.If(_node_loc(condition, self.filename), condition, blocks[0] if blocks else (), blocks[1] if len(blocks)>1 else ())
+    def while_stmt(self, items):
+        condition = items[0]; body = next((x for x in items[1:] if isinstance(x, tuple)), ())
+        return A.While(_node_loc(condition, self.filename), condition, body)
+    def block(self, items): return tuple(x for x in items if isinstance(x, A.Node))
+    def expr_stmt(self, items): return A.ExprStmt(_node_loc(items[0], self.filename), items[0])
+    def number(self, items):
+        s = str(items[0])
+        if len(s) > 1234: raise ParseError("Numeric literal exceeds the configured safety limit", location=_token_loc(items[0], self.filename))
+        return A.Literal(_token_loc(items[0], self.filename), float(s) if "." in s else int(s))
+    def string(self, items): return A.Literal(_token_loc(items[0], self.filename), _decode_string(str(items[0])))
+    def true(self, items): return A.Literal(_token_loc(items[0], self.filename), True)
+    def false(self, items): return A.Literal(_token_loc(items[0], self.filename), False)
+    def null(self, items): return A.Literal(_token_loc(items[0], self.filename), None)
+    def variable(self, items): return A.Variable(_token_loc(items[0], self.filename), str(items[0]))
+    def pycall_expr(self, items):
+        module, function = _decode_string(str(items[0])), _decode_string(str(items[1]))
+        if not all(part.isidentifier() and not part.startswith("_") for part in module.split(".")) or not function.isidentifier() or function.startswith("_"):
+            raise ParseError("pycall requires a module and public function name", location=_token_loc(items[0], self.filename))
+        return A.PythonCall(_token_loc(items[0], self.filename), module, function, tuple(items[2:]))
+    def unary_expr(self, items): return A.Unary(_token_loc(items[0], self.filename), "-" if str(items[0]) == "-" else "not", items[1])
+    def comparison(self, items): return _fold(items, self.filename)
+    def sum(self, items): return _fold(items, self.filename)
+    def term(self, items): return _fold(items, self.filename)
+
+def _token_loc(token: Token, filename: str) -> SourceLocation:
+    return SourceLocation(filename, getattr(token, "line", 1) or 1, getattr(token, "column", 1) or 1,
+                          getattr(token, "end_line", None), getattr(token, "end_column", None))
+def _node_loc(node, filename: str) -> SourceLocation:
+    return getattr(node, "loc", SourceLocation(filename))
+def _fold(items, filename):
+    if not items: raise AstError("Empty expression while building AST")
+    node = items[0]
+    for i in range(1, len(items), 2):
+        op, rhs = str(items[i]), items[i+1]
+        node = A.Binary(_node_loc(node, filename), node, op, rhs)
+    return node
+def _decode_string(s: str) -> str:
+    try: return py_ast.literal_eval(s)
+    except (ValueError, SyntaxError) as exc: raise ParseError("Invalid string literal", details=str(exc)) from exc
+
+def parse(source: str, filename: str = "<memory>") -> A.Program:
+    if not isinstance(source, str): raise ParseError("Source must be text", location=SourceLocation(filename))
+    try:
+        tree = _PARSER.parse(source)
+        result = _BuildAST(filename).transform(tree)
+    except RecursionError as exc:
+        raise ParseError("Expression nesting is too deep", location=SourceLocation(filename),
+                         suggestion="Simplify deeply nested expressions.") from exc
+    except UnexpectedInput as exc:
+        expected = ", ".join(sorted(getattr(exc, "expected", ()) or ()))
+        raise ParseError("Invalid syntax", location=SourceLocation(filename, exc.line or 1, exc.column or 1),
+                         details=f"Unexpected input. Expected: {expected or 'a valid expression or statement'}",
+                         suggestion="Check the highlighted line for missing quotes, operators, or braces.") from exc
+    except VisitError as exc:
+        orig = exc.orig_exc
+        if isinstance(orig, (ParseError, AstError)): raise orig
+        raise AstError("Could not construct a valid syntax tree", location=SourceLocation(filename), details=type(orig).__name__) from orig
+    if not isinstance(result, A.Program):
+        raise AstError("Parser did not produce a Program node", location=SourceLocation(filename))
+    return validate_ast(result)