narrativetrace-glossary 0.1.0__tar.gz

narrativetrace_glossary-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_glossary-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_glossary-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: narrativetrace-glossary
+Version: 0.1.0
+Summary: Domain glossary: ubiquitous-language harvesting and trace translation for narrativetrace
+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: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: narrativetrace
+Requires-Dist: narrativetrace-clarity
+Description-Content-Type: text/markdown
+
+# narrativetrace-glossary
+
+The domain glossary of a repository: one checked-in `glossary.json` that is simultaneously the
+translation dictionary, the reviewable domain documentation, and the vocabulary norm that clarity
+diagnostics enforce (ADR-012).
+
+The Java module `narrativetrace-glossary`. Platform mapping: Java *packages* become **dotted
+module-path prefixes**, so a bounded context owns `acme.billing`, not `com.acme.billing`.
+
+```python
+from narrativetrace_glossary import read_glossary_json, write_glossary_json
+
+glossary = read_glossary_json(Path("glossary.json").read_text(encoding="utf-8"))
+Path("glossary.json").write_text(write_glossary_json(glossary), encoding="utf-8")
+```
+
+Identifiers become glossary phrases through the normalizer, and the module path of the traced code
+picks the bounded context that owns them:
+
+```python
+from narrativetrace_glossary import method_candidates, normalize_phrase, resolve_context
+
+normalize_phrase("open_account_with_overdraft")   # "open account with overdraft"
+method_candidates("openAccountWithOverdraft")     # verb phrase + "account with overdraft"
+resolve_context(glossary, "acme.billing.overdraft_service")   # "billing"
+```
+
+Every spelling of one concept converges to a single phrase, so matching against terms and aliases
+always happens on the normalized form. Context prefixes match on dot boundaries — `acme.billing`
+owns `acme.billing.overdraft` but never the sibling `acme.billingx` — the longest match wins, and
+an unmatched path falls back to `_unassigned`, so harvesting works with zero configuration.
+
+The normalizer rejects anything that is not a single code identifier (blank, underscore-only, or
+whitespace-carrying input raises `ValueError`): a normalized phrase is term identity, so a
+non-canonical one would corrupt a glossary key.
+
+The writer is deterministic by construction — contexts sorted by name, terms in `(context, term)`
+order, fixed key order, 2-space indent, trailing newline — so a run that observes no new vocabulary
+leaves the committed file byte-identical.
+
+## Harvesting a run into the glossary
+
+`harvest_traces` observes captured trace trees; `merge_harvest` folds those observations into the
+committed glossary. Trace nodes carry a *simple* class name, so the caller supplies `module_of` to
+say which module declares it — production code passes `type(target).__module__`, tests pass a dict
+lookup. A name it cannot answer for resolves to `_unassigned`.
+
+```python
+from narrativetrace_glossary import harvest_traces, merge_harvest, write_glossary_json
+
+observed = harvest_traces(trees, glossary=glossary, module_of=modules.get)
+result = merge_harvest(glossary, observed)
+
+Path("glossary.json").write_text(write_glossary_json(result.glossary), encoding="utf-8")
+```
+
+Harvest sources are method names (the verb phrase plus the object noun phrase), parameter names,
+class names with a role suffix stripped, and the type name of whatever a node threw. Names that are
+no identifier — synthetic nodes like `<launcher>` or `fire-and-forget` — are skipped silently;
+harvesting is best-effort by design. Narration templates are *never* harvested from a live trace:
+they hold interpolated runtime values there.
+
+The merge is **additive-only** and **idempotent**, both property-tested. It never removes or
+rewrites an entry, so human-authored definitions, translations and a `curated` status are safe; a
+phrase that matches a term's deprecated synonym in its own context is suppressed rather than
+re-added, and comes back in `result.suppressed_alias_uses` for violation reporting. New terms are
+`harvested`, record at most three distinct sites, and are dated by an injectable `clock` that
+defaults to today in UTC — so the same run merged twice leaves the file byte-identical.

narrativetrace_glossary-0.1.0/README.md

@@ -0,0 +1,68 @@
+# narrativetrace-glossary
+
+The domain glossary of a repository: one checked-in `glossary.json` that is simultaneously the
+translation dictionary, the reviewable domain documentation, and the vocabulary norm that clarity
+diagnostics enforce (ADR-012).
+
+The Java module `narrativetrace-glossary`. Platform mapping: Java *packages* become **dotted
+module-path prefixes**, so a bounded context owns `acme.billing`, not `com.acme.billing`.
+
+```python
+from narrativetrace_glossary import read_glossary_json, write_glossary_json
+
+glossary = read_glossary_json(Path("glossary.json").read_text(encoding="utf-8"))
+Path("glossary.json").write_text(write_glossary_json(glossary), encoding="utf-8")
+```
+
+Identifiers become glossary phrases through the normalizer, and the module path of the traced code
+picks the bounded context that owns them:
+
+```python
+from narrativetrace_glossary import method_candidates, normalize_phrase, resolve_context
+
+normalize_phrase("open_account_with_overdraft")   # "open account with overdraft"
+method_candidates("openAccountWithOverdraft")     # verb phrase + "account with overdraft"
+resolve_context(glossary, "acme.billing.overdraft_service")   # "billing"
+```
+
+Every spelling of one concept converges to a single phrase, so matching against terms and aliases
+always happens on the normalized form. Context prefixes match on dot boundaries — `acme.billing`
+owns `acme.billing.overdraft` but never the sibling `acme.billingx` — the longest match wins, and
+an unmatched path falls back to `_unassigned`, so harvesting works with zero configuration.
+
+The normalizer rejects anything that is not a single code identifier (blank, underscore-only, or
+whitespace-carrying input raises `ValueError`): a normalized phrase is term identity, so a
+non-canonical one would corrupt a glossary key.
+
+The writer is deterministic by construction — contexts sorted by name, terms in `(context, term)`
+order, fixed key order, 2-space indent, trailing newline — so a run that observes no new vocabulary
+leaves the committed file byte-identical.
+
+## Harvesting a run into the glossary
+
+`harvest_traces` observes captured trace trees; `merge_harvest` folds those observations into the
+committed glossary. Trace nodes carry a *simple* class name, so the caller supplies `module_of` to
+say which module declares it — production code passes `type(target).__module__`, tests pass a dict
+lookup. A name it cannot answer for resolves to `_unassigned`.
+
+```python
+from narrativetrace_glossary import harvest_traces, merge_harvest, write_glossary_json
+
+observed = harvest_traces(trees, glossary=glossary, module_of=modules.get)
+result = merge_harvest(glossary, observed)
+
+Path("glossary.json").write_text(write_glossary_json(result.glossary), encoding="utf-8")
+```
+
+Harvest sources are method names (the verb phrase plus the object noun phrase), parameter names,
+class names with a role suffix stripped, and the type name of whatever a node threw. Names that are
+no identifier — synthetic nodes like `<launcher>` or `fire-and-forget` — are skipped silently;
+harvesting is best-effort by design. Narration templates are *never* harvested from a live trace:
+they hold interpolated runtime values there.
+
+The merge is **additive-only** and **idempotent**, both property-tested. It never removes or
+rewrites an entry, so human-authored definitions, translations and a `curated` status are safe; a
+phrase that matches a term's deprecated synonym in its own context is suppressed rather than
+re-added, and comes back in `result.suppressed_alias_uses` for violation reporting. New terms are
+`harvested`, record at most three distinct sites, and are dated by an injectable `clock` that
+defaults to today in UTC — so the same run merged twice leaves the file byte-identical.

narrativetrace_glossary-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "narrativetrace-glossary"
+version = "0.1.0"
+description = "Domain glossary: ubiquitous-language harvesting and trace translation for narrativetrace"
+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 = ["Typing :: Typed"]
+# Term normalization reuses the clarity distribution's tokenizer and lexical tables (ADR-012).
+# The core distribution is a direct dependency because harvesting walks its trace-tree types.
+dependencies = ["narrativetrace", "narrativetrace-clarity"]
+
+[project.urls]
+Homepage = "https://github.com/narrativetrace/narrativetrace-python"
+Source = "https://github.com/narrativetrace/narrativetrace-python"
+
+[project.scripts]
+# A deliberate, opt-in write tool (item 6's "glossary writes opt-in" prerequisite) — not a CI
+# gate, unlike narrativetrace-clarity's console script. See glossary_scan_cli's module docstring.
+glossary-scan = "narrativetrace_glossary.glossary_scan_cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/narrativetrace_glossary"]
+
+# Mutmut derives mutant keys from the run root, so it must run from this directory
+# (`uv run poe mutate-glossary`), not from the workspace root.
+[tool.mutmut]
+source_paths = ["src/narrativetrace_glossary/"]
+also_copy = ["tests/"]
+pytest_add_cli_args_test_selection = ["tests/"]
+# The pytest plugin distribution imports narrativetrace at plugin-load time, before the mutated
+# copy is on sys.path — loading it would test the installed package instead of the mutant.
+pytest_add_cli_args = ["-p", "no:narrativetrace"]

narrativetrace_glossary-0.1.0/src/narrativetrace_glossary/__init__.py

@@ -0,0 +1,114 @@
+"""Domain glossary for narrativetrace: ubiquitous language harvested from traces.
+
+One checked-in ``glossary.json`` per repository is at once the translation dictionary, the
+reviewable domain documentation, and the vocabulary norm clarity diagnostics enforce (ADR-012).
+"""
+
+from narrativetrace_glossary.alias_index import build_alias_index
+from narrativetrace_glossary.clarity_issues import (
+    NON_CANONICAL_TERM_CATEGORY,
+    non_canonical_term_issues,
+)
+from narrativetrace_glossary.context_resolver import UNASSIGNED_CONTEXT, resolve_context
+from narrativetrace_glossary.glossary_loader import load_glossary
+from narrativetrace_glossary.harvester import HarvestCandidate, harvest_traces
+from narrativetrace_glossary.json_reader import read_glossary_json
+from narrativetrace_glossary.json_writer import write_glossary_json
+from narrativetrace_glossary.markdown import render_glossary_markdown
+from narrativetrace_glossary.merger import MergeResult, merge_harvest
+from narrativetrace_glossary.models import (
+    GLOSSARY_ABBREVIATIONS_SCHEMA_VERSION,
+    GLOSSARY_SCHEMA_VERSION,
+    BoundedContext,
+    Glossary,
+    GlossaryTerm,
+    SynonymAlias,
+    TermKey,
+    TermKind,
+    TermStatus,
+)
+from narrativetrace_glossary.normalizer import (
+    TermCandidate,
+    class_candidate,
+    exception_candidate,
+    method_candidates,
+    normalize_phrase,
+    parameter_candidate,
+)
+from narrativetrace_glossary.rename_suggester import suggest_rename
+from narrativetrace_glossary.scaffolding import SUPPORTED_LOCALES, ScaffoldingBundle
+from narrativetrace_glossary.summary_formatter import (
+    format_violation_details,
+    format_vocabulary_summary,
+)
+from narrativetrace_glossary.translation_file_sink import TranslationFileSink
+from narrativetrace_glossary.translation_subscriber import (
+    DEFAULT_CAPACITY,
+    DEFAULT_TTL_SECONDS,
+    TranslationSubscriber,
+)
+from narrativetrace_glossary.translation_view import RenderState, TraceTranslationView
+from narrativetrace_glossary.translator import GlossaryTranslator, PhraseTranslation
+from narrativetrace_glossary.usage_report import (
+    USAGE_REPORT_FILE,
+    usage_report_document,
+    write_usage_report,
+)
+from narrativetrace_glossary.violations import VocabularyViolation, aggregate_violations
+from narrativetrace_glossary.vocabulary import (
+    GLOSSARY_FILE,
+    glossary_vocabulary,
+    read_project_vocabulary,
+)
+
+__all__ = [
+    "DEFAULT_CAPACITY",
+    "DEFAULT_TTL_SECONDS",
+    "GLOSSARY_ABBREVIATIONS_SCHEMA_VERSION",
+    "GLOSSARY_FILE",
+    "GLOSSARY_SCHEMA_VERSION",
+    "NON_CANONICAL_TERM_CATEGORY",
+    "SUPPORTED_LOCALES",
+    "UNASSIGNED_CONTEXT",
+    "USAGE_REPORT_FILE",
+    "BoundedContext",
+    "Glossary",
+    "GlossaryTerm",
+    "GlossaryTranslator",
+    "HarvestCandidate",
+    "MergeResult",
+    "PhraseTranslation",
+    "RenderState",
+    "ScaffoldingBundle",
+    "SynonymAlias",
+    "TermCandidate",
+    "TermKey",
+    "TermKind",
+    "TermStatus",
+    "TraceTranslationView",
+    "TranslationFileSink",
+    "TranslationSubscriber",
+    "VocabularyViolation",
+    "aggregate_violations",
+    "build_alias_index",
+    "class_candidate",
+    "exception_candidate",
+    "format_violation_details",
+    "format_vocabulary_summary",
+    "glossary_vocabulary",
+    "harvest_traces",
+    "load_glossary",
+    "merge_harvest",
+    "method_candidates",
+    "non_canonical_term_issues",
+    "normalize_phrase",
+    "parameter_candidate",
+    "read_glossary_json",
+    "read_project_vocabulary",
+    "render_glossary_markdown",
+    "resolve_context",
+    "suggest_rename",
+    "usage_report_document",
+    "write_glossary_json",
+    "write_usage_report",
+]

narrativetrace_glossary-0.1.0/src/narrativetrace_glossary/alias_index.py

@@ -0,0 +1,53 @@
+"""Lookup from ``(context, normalized alias)`` to the canonical term that deprecates it.
+
+``AliasIndex``, whose three methods collapse into one function returning a read-only
+mapping: ``key in index`` answers Java's ``isAlias`` and ``index.get(key)`` answers its
+``canonicalFor``. INTENT: harvesting and violation reporting both ask the same question, so the
+answer is precomputed once per glossary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from narrativetrace_glossary.models import Glossary, GlossaryTerm, TermKey
+
+
+def build_alias_index(glossary: Glossary) -> Mapping[TermKey, GlossaryTerm]:
+    """Indexes every ``(term context, synonym alias)`` pair the glossary declares.
+
+    Matching is exact on the whole normalized phrase — neither a substring nor a superstring of an
+    alias is one — and scoped per context, so an alias is recognized only where its canonical term
+    is defined.
+
+    Returns:
+        A read-only mapping; a phrase absent from it is not a deprecated alias.
+
+    Raises:
+        TypeError: if ``glossary`` is not a :class:`Glossary`.
+    """
+    if not isinstance(glossary, Glossary):
+        raise TypeError("glossary must be a Glossary")
+    index = MappingProxyType(
+        {
+            TermKey(term.context, synonym.alias): term
+            for term in glossary.terms
+            for synonym in term.synonyms
+        }
+    )
+    assert _invariant(index), "every indexed key must name an alias of the term it maps to"
+    return index
+
+
+def _invariant(index: Mapping[TermKey, GlossaryTerm]) -> bool:
+    """Returns whether an index is consistent with the terms it points at.
+
+    Every key must be filed under its canonical term's own context and name a phrase that term
+    actually deprecates — otherwise a lookup would suppress a harvest on someone else's behalf.
+    """
+    return all(
+        key.context == term.context
+        and any(synonym.alias == key.normalized for synonym in term.synonyms)
+        for key, term in index.items()
+    )

narrativetrace_glossary-0.1.0/src/narrativetrace_glossary/clarity_issues.py

@@ -0,0 +1,47 @@
+"""Maps vocabulary violations onto the clarity issue model.
+
+``NonCanonicalTermIssues``. INTENT: a deprecated phrasing is a naming-clarity concern like
+any other, so it rides the same ``ClarityIssue``/``Severity`` pipeline the built-in scorers use —
+one issue category, ``non-canonical-term``, contributed by the glossary rather than a dictionary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from narrativetrace_clarity import ClarityIssue, Severity
+
+from narrativetrace_glossary.violations import VocabularyViolation
+
+NON_CANONICAL_TERM_CATEGORY = "non-canonical-term"
+"""Clarity issue category for a phrasing the glossary has deprecated."""
+
+
+def _suggestion(violation: VocabularyViolation) -> str:
+    return (
+        f"'{violation.alias}' is deprecated in favor of '{violation.canonical_term}' "
+        f"(rename to '{violation.suggested_rename}')"
+    )
+
+
+def _issue_of(violation: VocabularyViolation) -> ClarityIssue:
+    base = ClarityIssue(
+        category=NON_CANONICAL_TERM_CATEGORY,
+        element=f"{violation.site}: {violation.identifier}",
+        suggestion=_suggestion(violation),
+        severity=Severity.MEDIUM,
+    )
+    return base.with_occurrences(violation.occurrences)
+
+
+def non_canonical_term_issues(
+    violations: Sequence[VocabularyViolation],
+) -> tuple[ClarityIssue, ...]:
+    """Converts vocabulary violations into ``non-canonical-term`` clarity issues, one per violation.
+
+    Severity is always :attr:`~narrativetrace_clarity.Severity.MEDIUM` — a deprecated phrasing is
+    a real naming defect, but never as severe as ``HIGH``-tier structural issues (matches the
+    plan's advisory-by-default posture: suite issues are logged, and only fail a build that opts in
+    via a hard cap).
+    """
+    return tuple(_issue_of(violation) for violation in violations)

narrativetrace_glossary-0.1.0/src/narrativetrace_glossary/clarity_scan.py

@@ -0,0 +1,30 @@
+"""Glossary-aware entry point for the clarity gate — vocabulary-check defaults (prerequisite 5).
+
+``GlossaryAwareClarityScannerMain``. INTENT: composes ``narrativetrace-clarity``'s CLI
+with :func:`~narrativetrace_glossary.vocabulary.read_project_vocabulary` without either package
+importing the other's internals — ``narrativetrace_clarity.cli.main`` takes the reader as a plain
+callback (see its module docstring). The root ``clarity`` gate task runs *this* module, not
+``narrativetrace-clarity`` directly, which is what makes glossary-aware scoring the actual default:
+a project with no committed glossary degrades to the built-in dictionaries exactly as before,
+silently and without a separate opt-in flag.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from narrativetrace_clarity.cli import main as _clarity_main
+
+from narrativetrace_glossary.vocabulary import read_project_vocabulary
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Runs the clarity scan/gate with the repository's committed glossary as domain vocabulary."""
+    return _clarity_main(argv, vocabulary_reader=read_project_vocabulary)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

narrativetrace_glossary-0.1.0/src/narrativetrace_glossary/class_package_index.py

@@ -0,0 +1,65 @@
+"""Builds a ``class_name -> module path`` lookup from already-captured trace trees.
+
+``ClassPackageIndex`` (Java's compiled-class-directory scan, .NET's loaded-assembly
+scan). INTENT: :func:`~narrativetrace_glossary.harvester.harvest_traces` takes a ``module_of``
+callable but does not build one itself — every runtime resolves it differently. Here, the resolver
+that matters is trivial: :attr:`~narrativetrace.signature.MethodSignature.package_name` is already
+captured on every node (``__module__`` at trace time), so this only needs to aggregate it and
+resolve ambiguity, never scan anything.
+
+**Do not default this to "always None".** A prior mirror (dotnet, audit finding G1a) shipped a
+suite reporter that passed a namespace resolver returning ``None`` unconditionally, so every
+harvested term landed in ``_unassigned`` and every bounded context a project declared was
+decoration. Ambiguity is resolved to ``None`` deliberately (a class name seen under two different
+modules names no single context); *absence of any observation* must never be confused with that —
+it is also ``None``, but for the ordinary reason that harvesting only ever sees the classes a run
+actually touched.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from narrativetrace.tree import TraceTree
+from narrativetrace.tree_walk import TreeWalk
+
+
+def _walk(tree_roots: Sequence[object], observed: dict[str, set[str | None]]) -> None:
+    walk = TreeWalk()
+    _walk_nodes(tree_roots, observed, walk)
+
+
+def _walk_nodes(
+    nodes: Sequence[object], observed: dict[str, set[str | None]], walk: TreeWalk
+) -> None:
+    for node in nodes:
+        signature = node.signature  # type: ignore[attr-defined]
+        observed.setdefault(signature.class_name, set()).add(signature.package_name)
+        if walk.stop_reason(node) is None:
+            walk.enter(node)
+            try:
+                _walk_nodes(node.children, observed, walk)  # type: ignore[attr-defined]
+            finally:
+                walk.exit(node)
+
+
+def class_package_index(trees: Sequence[TraceTree]) -> Callable[[str], str | None]:
+    """Builds a ``module_of`` resolver from the ``package_name`` every node already carries.
+
+    A class name observed under exactly one non-``None`` module resolves to it; observed under two
+    or more distinct modules (or never observed, or only ever observed without a captured module)
+    resolves to ``None`` — files that class's terms under ``_unassigned`` rather than guessing.
+
+    Returns:
+        A callable suitable as :func:`~narrativetrace_glossary.harvester.harvest_traces`'s
+        ``module_of`` argument.
+    """
+    observed: dict[str, set[str | None]] = {}
+    for tree in trees:
+        _walk(tree.roots, observed)
+    resolved = {
+        class_name: next(iter(modules))
+        for class_name, modules in observed.items()
+        if len(modules) == 1 and next(iter(modules)) is not None
+    }
+    return resolved.get

narrativetrace_glossary-0.1.0/src/narrativetrace_glossary/context_resolver.py

@@ -0,0 +1,40 @@
+"""Resolves the dotted module path of traced code to the bounded context that owns it.
+
+``ContextResolver``, whose Java package prefixes become dotted module-path prefixes
+(``acme.billing``, not ``com.acme.billing``). INTENT: contexts declare their prefixes in the
+glossary file itself, so the file stays the single source of truth.
+"""
+
+from __future__ import annotations
+
+from narrativetrace_glossary.models import Glossary
+
+UNASSIGNED_CONTEXT = "_unassigned"
+"""Fallback context for module paths no declared context owns."""
+
+
+def resolve_context(glossary: Glossary, module_path: str) -> str:
+    """Resolves a module path to the name of the context that declares a matching prefix.
+
+    The longest matching prefix wins, so contexts may nest; no match resolves to
+    :data:`UNASSIGNED_CONTEXT`, which is what lets harvesting work with zero configuration.
+    """
+    owners = [
+        (len(prefix), name)
+        for name in sorted(glossary.contexts)
+        for prefix in glossary.contexts[name].packages
+        if _owns(prefix, module_path)
+    ]
+    if not owners:
+        return UNASSIGNED_CONTEXT
+    # Sorted iteration plus max()'s first-maximal rule makes equal-length ties deterministic:
+    # the alphabetically first context name wins.
+    return max(owners, key=lambda owner: owner[0])[1]
+
+
+def _owns(prefix: str, module_path: str) -> bool:
+    """Delimiter-aware prefix test: the module itself, or a child module separated by a dot.
+
+    ``acme.billing`` owns ``acme.billing.overdraft`` but never the sibling ``acme.billingx``.
+    """
+    return module_path == prefix or module_path.startswith(f"{prefix}.")