narrativetrace-pytest 0.1.0__tar.gz

narrativetrace_pytest-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.mutmut-cache
+mutants/
+# pytest-benchmark autosave (poe bench-gate): per-machine comparison history, never comparable
+# across machines -- stays local to whichever machine runs the nightly, like .venv/.uv-cache.
+.benchmarks/
+htmlcov/
+.coverage
+.coverage.*
+dist/
+build/
+*.egg-info/
+
+# Cache for security-tool binaries auto-fetched by scripts/run_security_tool.py
+.tools/
+
+# Local tooling state (contains credentials — never commit)
+.devcontainer/claude-home/
+.agent-run*
+
+# Local tooling state (holds host-absolute paths)
+.claude/settings.local.json

narrativetrace_pytest-0.1.0/LICENSE

@@ -0,0 +1,99 @@
+Business Source License 1.1
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Empower Agile
+
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version {{VERSION}}. The Licensed Work is (c) 2026 Empower Agile.
+
+Additional Use Grant: You may make production use of the Licensed Work for any
+                      purpose, including internal use and use in products and
+                      services you provide to your own customers, provided that
+                      such production use does not include offering the
+                      Licensed Work, or a product or service whose value
+                      derives substantially from the Licensed Work, to third
+                      parties as a logging, tracing, or code-narrative product
+                      or service.
+
+Change Date:          Four years from the date the Licensed Work is published. ({{CHANGE_DATE}} for this version)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Empower Agile at hello@narrativetrace.ai.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

narrativetrace_pytest-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: narrativetrace-pytest
+Version: 0.1.0
+Summary: pytest plugin for narrativetrace: per-test trace fixtures, artifacts, and reporting
+Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
+Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python
+Author: narrativetrace contributors
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Classifier: Framework :: Pytest
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: narrativetrace
+Requires-Dist: narrativetrace-clarity
+Requires-Dist: narrativetrace-diagrams
+Requires-Dist: narrativetrace-glossary
+Requires-Dist: pytest>=8
+Description-Content-Type: text/markdown
+
+# narrativetrace-pytest
+
+pytest plugin for [narrativetrace](../narrativetrace): a `narrative_trace` fixture, per-test
+trace artifacts, failure execution-trace reports, and a suite summary reporter.

narrativetrace_pytest-0.1.0/README.md

@@ -0,0 +1,4 @@
+# narrativetrace-pytest
+
+pytest plugin for [narrativetrace](../narrativetrace): a `narrative_trace` fixture, per-test
+trace artifacts, failure execution-trace reports, and a suite summary reporter.

narrativetrace_pytest-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "narrativetrace-pytest"
+version = "0.1.0"
+description = "pytest plugin for narrativetrace: per-test trace fixtures, artifacts, and reporting"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BUSL-1.1"
+# See packages/narrativetrace/pyproject.toml: one byte-identical copy of the root LICENSE per
+# distribution, because PEP 639 forbids reaching out of the project directory.
+license-files = ["LICENSE"]
+authors = [{ name = "narrativetrace contributors" }]
+classifiers = [
+    "Framework :: Pytest",
+    "Typing :: Typed",
+]
+dependencies = [
+    "narrativetrace",
+    "narrativetrace-diagrams",
+    "narrativetrace-clarity",
+    "narrativetrace-glossary",
+    "pytest>=8",
+]
+
+[project.urls]
+Homepage = "https://github.com/narrativetrace/narrativetrace-python"
+Source = "https://github.com/narrativetrace/narrativetrace-python"
+
+[project.entry-points.pytest11]
+narrativetrace = "narrativetrace_pytest.plugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/narrativetrace_pytest"]

narrativetrace_pytest-0.1.0/src/narrativetrace_pytest/__init__.py

@@ -0,0 +1,3 @@
+"""pytest plugin for narrativetrace."""
+
+__version__ = "0.1.0"

narrativetrace_pytest-0.1.0/src/narrativetrace_pytest/plugin.py

@@ -0,0 +1,316 @@
+"""The narrativetrace pytest plugin: fixture, per-test artifacts, and suite reporting.
+
+The JUnit4/5 extension behaviours (testfx-logging-otel §TS-TESTFX-*). The ``narrative_trace``
+fixture builds a fresh context at the env-configured level; on teardown it emits template warnings,
+prints a framed execution trace for failed tests, and (when output is enabled) writes per-test
+artifacts. A session reporter prints the suite header/footer.
+
+Artifacts match the Java JUnit integration so conformance fixtures can compare them across
+platforms: the ``.json`` companion is the full ``export_document`` envelope (``version`` +
+``scenario``), and the scenario result travels as a
+:class:`~narrativetrace.render.scenario_result.ScenarioResult` — ``success``/``error`` in the JSON
+artifact, ``PASSED``/``FAILED`` in the Markdown caption.
+
+Environment channels: ``NARRATIVETRACE_LEVEL`` (garbage → DETAIL), ``NARRATIVETRACE_OUTPUT``
+(truthy → write files), ``NARRATIVETRACE_OUTPUT_DIR`` (default ``narrative-traces``),
+``NARRATIVETRACE_FORMAT`` (default ``markdown``; ``text``/``mermaid``/``plantuml`` replace the
+Markdown trace, and only ``markdown`` carries the ``.json`` + ``.mmd`` companions),
+``NARRATIVETRACE_CANONICAL`` (truthy → also write the per-test ``.canonical.json`` entry array,
+whatever the format; off by default because it is a machine artifact for conformance runners).
+
+Clarity aggregation (PY12): each test's captured tree is scored, the suite footer prints a
+high/moderate/low split, and (when output is enabled) a ``clarity-results.json`` plus Markdown
+suite report are written with one entry per test (duplicate scenario names retained).
+
+Loss reporting: each test's :meth:`~narrativetrace.context.NarrativeContext.trace_loss` reading is
+summed (one context per test, so readings add rather than needing a difference), and the footer
+names what the suite lost on one line — omitted entirely when it lost nothing.
+
+Glossary harvest hook (Phase 5): opt-in by ``glossary.json`` presence — a suite harvests only when
+the repository has already committed a glossary, unless ``NARRATIVETRACE_GLOSSARY`` overrides that
+default (``off`` disables unconditionally; any other truthy value forces harvesting even with no
+glossary.json yet, which then creates one). Distinct from ``NARRATIVETRACE_GLOSSARY_DIR``, which
+names *where* the glossary lives for both this hook and the unconditional vocabulary read above;
+harvesting itself always writes the merged glossary/usage report back once it runs, independent of
+``NARRATIVETRACE_OUTPUT`` (that key gates trace-file artifacts, an unrelated concern).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+from narrativetrace_clarity import analyze as analyze_clarity
+from narrativetrace_clarity import export as export_clarity
+from narrativetrace_clarity import render_suite_report
+from narrativetrace_clarity.models import ClarityResult
+from narrativetrace_clarity.vocabulary import EMPTY, DomainVocabulary
+from narrativetrace_diagrams.mermaid import MermaidSequenceDiagramRenderer
+from narrativetrace_diagrams.plantuml import PlantUmlSequenceDiagramRenderer
+from narrativetrace_glossary.class_package_index import class_package_index
+from narrativetrace_glossary.harvester import harvest_traces
+from narrativetrace_glossary.json_reader import read_glossary_json
+from narrativetrace_glossary.models import Glossary
+from narrativetrace_glossary.suite_harvest import GLOSSARY_JSON_FILE, run_suite_harvest
+from narrativetrace_glossary.summary_formatter import format_violation_details
+from narrativetrace_glossary.vocabulary import read_project_vocabulary
+
+from narrativetrace.config import ConfigResolver
+from narrativetrace.context import ContextVarNarrativeContext
+from narrativetrace.export import export_document as export_document_json
+from narrativetrace.levels import NarrativeTraceConfig
+from narrativetrace.loss import TraceLoss
+from narrativetrace.output.reporter import ConsoleSummaryReporter
+from narrativetrace.output.warnings import collect, format_warnings
+from narrativetrace.output.writer import TraceArtifact, write_trace
+from narrativetrace.render.base import TraceMetadata
+from narrativetrace.render.scenario import humanize
+from narrativetrace.render.scenario_result import ScenarioResult
+from narrativetrace.tree import TraceTree
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+@dataclass(slots=True)
+class _OutputSettings:
+    enabled: bool
+    base_dir: Path
+    fmt: str
+    canonical: bool = False
+
+
+def _truthy(resolver: ConfigResolver, key: str) -> bool:
+    return (resolver.resolve(key, "") or "").strip().lower() in _TRUTHY
+
+
+def _output_settings(resolver: ConfigResolver) -> _OutputSettings:
+    """Reads the output keys through the shared precedence chain (env → config file → default)."""
+    enabled = _truthy(resolver, "output")
+    base_dir = Path((resolver.resolve("output_dir", "") or "").strip() or "narrative-traces")
+    fmt = (resolver.resolve("format", "") or "").strip() or "markdown"
+    return _OutputSettings(enabled, base_dir, fmt, _truthy(resolver, "canonical"))
+
+
+def _resolver(config: pytest.Config) -> ConfigResolver:
+    """One resolver per session — file discovery walks the filesystem and must not run per test."""
+    existing = getattr(config, "_narrativetrace_resolver", None)
+    if existing is None:
+        existing = ConfigResolver()
+        config._narrativetrace_resolver = existing  # type: ignore[attr-defined]
+    return existing
+
+
+@dataclass(slots=True)
+class _SuiteAccumulator:
+    scenarios: list[str] = field(default_factory=list)
+    clarity: list[tuple[str, ClarityResult]] = field(default_factory=list)
+    loss: TraceLoss = field(default_factory=TraceLoss.none)
+    harvest_trees: list[TraceTree] = field(default_factory=list)
+
+
+def _glossary_dir(config: pytest.Config) -> str:
+    return (_resolver(config).resolve("glossary_dir", "") or "").strip() or "."
+
+
+def _harvest_enabled(config: pytest.Config) -> bool:
+    """Opt-in by ``glossary.json`` presence, with an explicit ``NARRATIVETRACE_GLOSSARY`` override.
+
+    ``off`` disables harvesting unconditionally, even with a glossary already committed — the
+    mid-suite equivalent of Java's suite extension defaulting to ``disabled()``. Any other truthy
+    value forces harvesting on, even with no ``glossary.json`` yet (a project's first opt-in run,
+    which then creates one). Unset defaults to "harvest only when a glossary.json already exists"
+    — the least-surprising default: a project that has never curated a glossary does not get one
+    silently written just by running its test suite.
+    """
+    override = (_resolver(config).resolve("glossary", "") or "").strip().lower()
+    if override == "off":
+        return False
+    if override in _TRUTHY:
+        return True
+    return (Path(_glossary_dir(config)) / GLOSSARY_JSON_FILE).is_file()
+
+
+def _project_vocabulary(config: pytest.Config) -> DomainVocabulary:
+    """The repository's committed glossary, read once per session as the scoring vocabulary.
+
+    Unlike harvesting, reading is unconditional: it changes nothing on disk, and a project that
+    curates its ubiquitous language should not have to opt in to being scored in it. Only the
+    committed file counts — nothing this run harvests feeds back into its own scores.
+
+    ``narrativetrace.glossary_dir`` (env ``NARRATIVETRACE_GLOSSARY_DIR``) names the directory,
+    defaulting to the working directory. A glossary that cannot be read degrades to the built-in
+    dictionaries with a warning: a reporting artifact must never fail the suite that produced it.
+    """
+    existing = getattr(config, "_narrativetrace_vocabulary", None)
+    if existing is not None:
+        return cast("DomainVocabulary", existing)
+    glossary_dir = _glossary_dir(config)
+    try:
+        resolved = read_project_vocabulary(glossary_dir)
+    except (OSError, ValueError) as error:
+        print(
+            f"narrative-trace: committed glossary at {glossary_dir} could not be read, "
+            f"scoring with the built-in dictionaries only ({error})"
+        )
+        resolved = EMPTY
+    config._narrativetrace_vocabulary = resolved  # type: ignore[attr-defined]
+    return resolved
+
+
+def _accumulator(config: pytest.Config) -> _SuiteAccumulator:
+    existing = getattr(config, "_narrativetrace_acc", None)
+    if existing is None:
+        existing = _SuiteAccumulator()
+        config._narrativetrace_acc = existing  # type: ignore[attr-defined]
+    return existing
+
+
+def _class_name(request: pytest.FixtureRequest) -> str:
+    node_cls = getattr(request.node, "cls", None)
+    if node_cls is not None:
+        return str(node_cls.__name__)
+    return str(request.module.__name__).rsplit(".", 1)[-1]
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[Any]) -> Iterator[None]:
+    outcome = yield
+    report = outcome.get_result()  # type: ignore[attr-defined]
+    setattr(item, f"_nt_rep_{report.when}", report)
+
+
+@pytest.fixture
+def narrative_trace(request: pytest.FixtureRequest) -> Iterator[ContextVarNarrativeContext]:
+    """A fresh capture context at the env-configured level; writes artifacts on teardown."""
+    context = ContextVarNarrativeContext(
+        NarrativeTraceConfig.resolve(resolver=_resolver(request.config))
+    )
+    yield context
+    _finish(context, request)
+
+
+def _finish(context: ContextVarNarrativeContext, request: pytest.FixtureRequest) -> None:
+    """Teardown: aggregate for the suite, surface template warnings, write per-test artifacts."""
+    tree = context.capture_trace()
+    scenario = humanize(request.node.name)
+    _accumulate(request.config, scenario, tree, context.trace_loss())
+
+    warning_text = format_warnings(collect(tree))
+    if warning_text:
+        print(warning_text)
+
+    report = getattr(request.node, "_nt_rep_call", None)
+    _write_artifacts(tree, scenario, request, failed=report is not None and report.failed)
+
+
+def _accumulate(config: pytest.Config, scenario: str, tree: TraceTree, loss: TraceLoss) -> None:
+    """Records the scenario for the footer, scoring clarity for non-empty traces.
+
+    Each test gets its own context, so per-test readings sum: nothing is double-counted the way
+    a difference against a process-wide counter would be.
+    """
+    accumulator = _accumulator(config)
+    accumulator.scenarios.append(scenario)
+    accumulator.loss = accumulator.loss.plus(loss)
+    if not tree.is_empty:  # clarity aggregates non-empty traces (Java's GlobalTraceAccumulator)
+        accumulator.clarity.append((scenario, analyze_clarity(tree, _project_vocabulary(config))))
+        if _harvest_enabled(config):
+            accumulator.harvest_trees.append(tree)
+
+
+def _write_artifacts(
+    tree: TraceTree, scenario: str, request: pytest.FixtureRequest, *, failed: bool
+) -> None:
+    """Writes this test's trace artifacts when output is enabled and anything was captured."""
+    settings = _output_settings(_resolver(request.config))
+    if not settings.enabled or tree.is_empty:
+        return
+    metadata = TraceMetadata(scenario, ScenarioResult.of(failed))
+    write_result = write_trace(
+        tree,
+        metadata,
+        TraceArtifact(
+            settings.base_dir,
+            _class_name(request),
+            request.node.name,
+            settings.fmt,
+            canonical=settings.canonical,
+        ),
+        json_exporter=lambda captured: export_document_json(captured, metadata),
+        diagram_renderer=MermaidSequenceDiagramRenderer().render,
+        plantuml_renderer=PlantUmlSequenceDiagramRenderer().render,
+    )
+    if write_result.files:
+        print(write_result.console_echo)
+
+
+def pytest_terminal_summary(terminalreporter: Any) -> None:
+    """Prints the suite footer with the clarity split; writes clarity artifacts if enabled."""
+    accumulator = getattr(terminalreporter.config, "_narrativetrace_acc", None)
+    if accumulator is None or not accumulator.scenarios:
+        return
+    reporter = ConsoleSummaryReporter()
+    settings = _output_settings(_resolver(terminalreporter.config))
+    scores = [result.overall_score for _, result in accumulator.clarity]
+    terminalreporter.write_line(
+        reporter.format_suite_footer(
+            len(accumulator.scenarios), str(settings.base_dir), scores, accumulator.loss
+        )
+    )
+    if settings.enabled and accumulator.clarity:
+        _write_clarity_reports(accumulator.clarity, settings.base_dir)
+    if accumulator.harvest_trees:
+        _run_harvest(
+            terminalreporter.config, accumulator.harvest_trees, settings.base_dir, terminalreporter
+        )
+
+
+def _write_clarity_reports(clarity: list[tuple[str, ClarityResult]], base_dir: Path) -> None:
+    base_dir.mkdir(parents=True, exist_ok=True)
+    (base_dir / "clarity-results.json").write_text(export_clarity(clarity), encoding="utf-8")
+    (base_dir / "clarity-report.md").write_text(render_suite_report(clarity), encoding="utf-8")
+
+
+def _context_glossary(glossary_dir: str) -> Glossary:
+    """Reads the committed glossary for bounded-context resolution only.
+
+    Separate from :func:`~narrativetrace_glossary.suite_harvest.run_suite_harvest`'s own read of
+    the same file (for the merge) — a malformed file must not break context resolution silently,
+    so this degrades to an empty glossary (every candidate files under ``_unassigned``) rather than
+    raising into a terminal-summary hook that must never crash the suite that already passed.
+    """
+    path = Path(glossary_dir) / GLOSSARY_JSON_FILE
+    if not path.is_file():
+        return Glossary()
+    try:
+        return read_glossary_json(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return Glossary()
+
+
+def _run_harvest(
+    config: pytest.Config, trees: list[TraceTree], base_dir: Path, terminalreporter: Any
+) -> None:
+    """Harvests, merges, writes back, and reports — the opt-in half of glossary maintenance.
+
+    A failure here (a malformed committed glossary, an unwritable directory) is reported and
+    swallowed: harvesting is a maintenance side effect of running the suite, never a reason the
+    suite itself should be reported as broken.
+    """
+    glossary_dir = _glossary_dir(config)
+    try:
+        module_of = class_package_index(trees)
+        candidates = harvest_traces(
+            trees, glossary=_context_glossary(glossary_dir), module_of=module_of
+        )
+        result = run_suite_harvest(candidates, glossary_dir=glossary_dir, output_dir=str(base_dir))
+    except (OSError, ValueError) as error:
+        terminalreporter.write_line(f"narrative-trace: glossary harvest failed, skipped ({error})")
+        return
+    terminalreporter.write_line(result.summary)
+    details = format_violation_details(result.violations)
+    if details:
+        terminalreporter.write_line(details)