akms-learn 0.3.0__tar.gz

akms_learn-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Shmuel Osovski
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

akms_learn-0.3.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: akms-learn
+Version: 0.3.0
+Summary: Learning Source Packet compiler and exporters for AKMS (experimental preview)
+Author: Shmuel Osovski
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: akms
+Requires-Dist: nbformat<6,>=5
+Requires-Dist: jinja2<4,>=3
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: pyyaml<7,>=6.0.3
+Requires-Dist: networkx<4,>=3.0
+Requires-Dist: markdown-it-py<5,>=3
+Provides-Extra: notebook
+Provides-Extra: html
+Provides-Extra: llm
+Provides-Extra: nlm
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Dynamic: license-file
+
+# akms-learn
+
+> **Experimental preview.** This package ships as a clearly-labeled preview:
+> its API and output formats may change between minor releases, and it is not
+> yet covered by the stability promises of the core `akms` package.
+
+Learning Source Packet (LSP) compiler and exporters for the AKMS framework.
+
+- Distribution name: `akms-learn`
+- Import name: `akms_learn`
+- Python: `>=3.12,<3.13`
+- CLI: `akms-learn`
+- Plugin entry point: `akms.plugins` / `learn`
+
+The package depends on `akms` for read-only graph and schema access. The reverse
+direction is forbidden and tested: core never imports `akms_learn`.
+
+`nbformat` and Jinja2 are base dependencies, so notebook and HTML features work
+without an extras install. The `notebook` and `html` extras remain empty
+compatibility sentinels. The `nlm` extra is also a sentinel because the grounded
+NotebookLM provider probes the external `nlm` executable at runtime.
+
+See the unified documentation: `docs/getting-started/akms-learn.md`, `docs/concepts/akms-learn.md`, and `docs/reference/akms-learn/`.

akms_learn-0.3.0/README.md

@@ -0,0 +1,23 @@
+# akms-learn
+
+> **Experimental preview.** This package ships as a clearly-labeled preview:
+> its API and output formats may change between minor releases, and it is not
+> yet covered by the stability promises of the core `akms` package.
+
+Learning Source Packet (LSP) compiler and exporters for the AKMS framework.
+
+- Distribution name: `akms-learn`
+- Import name: `akms_learn`
+- Python: `>=3.12,<3.13`
+- CLI: `akms-learn`
+- Plugin entry point: `akms.plugins` / `learn`
+
+The package depends on `akms` for read-only graph and schema access. The reverse
+direction is forbidden and tested: core never imports `akms_learn`.
+
+`nbformat` and Jinja2 are base dependencies, so notebook and HTML features work
+without an extras install. The `notebook` and `html` extras remain empty
+compatibility sentinels. The `nlm` extra is also a sentinel because the grounded
+NotebookLM provider probes the external `nlm` executable at runtime.
+
+See the unified documentation: `docs/getting-started/akms-learn.md`, `docs/concepts/akms-learn.md`, and `docs/reference/akms-learn/`.

akms_learn-0.3.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "akms-learn"
+version = "0.3.0"
+description = "Learning Source Packet compiler and exporters for AKMS (experimental preview)"
+requires-python = ">=3.12,<3.13"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "Shmuel Osovski" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "akms",
+    # nbformat + jinja2 are now BASE deps (previously the [notebook]/[html]
+    # extras) so notebook/html features — assessment_first, quiz_export,
+    # html_export, notebook_source, notebook_export — work out of the box
+    # without an extras install. The [notebook]/[html] keys below are kept as
+    # empty sentinels for backward compatibility.
+    "nbformat>=5,<6",
+    "jinja2>=3,<4",
+    "pydantic>=2.7,<3.0",
+    "pyyaml>=6.0.3,<7",
+    "networkx>=3.0,<4",
+    "markdown-it-py>=3,<5",
+]
+
+[project.optional-dependencies]
+# nbformat/jinja2 moved to base dependencies above; these stay as empty
+# sentinels so `akms-learn[notebook]` / `akms-learn[html]` keep resolving.
+notebook = []
+html = []
+llm = []
+# Grounded NotebookLM provider. The `nlm` CLI is an external
+# binary, not a pip package, so this extra is an empty sentinel: availability is
+# probed at runtime via shutil.which("nlm"). Listed so the capability gate and
+# downstream consumers can declare intent.
+nlm = []
+dev = [
+    "pytest>=9.0.2",
+]
+
+[project.scripts]
+akms-learn = "akms_learn.cli:main"
+
+[project.entry-points."akms.plugins"]
+learn = "akms_learn.plugin:get_plugin"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "unit: fast unit-level tests",
+    "integration: cross-module/integration tests",
+    "regression: regression and backfill-evidence tests",
+    "e2e: end-to-end tests exercising the full pipeline",
+]

akms_learn-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

akms_learn-0.3.0/src/akms_learn/__init__.py

@@ -0,0 +1,155 @@
+"""akms_learn: Learning Source Packet compiler and exporters for AKMS."""
+
+from akms_learn.cli import main
+from akms_learn.compiler import (
+    STAGES,
+    CompileResult,
+    compile_learning_source,
+)
+from akms_learn.domain_packs import (
+    CapabilityStatus,
+    CompanionRole,
+    DomainPackDescriptor,
+    DomainPackRegistry,
+    DomainPackWarning,
+    LearningCapabilityError,
+    RuntimeHint,
+    SourcePackDescriptor,
+    build_registry_from_paths,
+    load_descriptor_from_yaml,
+    load_source_pack_from_yaml,
+    warn_planned_companion,
+)
+from akms_learn.exporters.bundle import MANIFEST_VERSION
+from akms_learn.exporters.bundle import export as bundle_export
+from akms_learn.exporters.markdown import export as markdown_export
+from akms_learn.graph_import import (
+    GraphSlice,
+    compute_graph_hash,
+    fixture_graph,
+    load_graph,
+)
+from akms_learn.modes.anthology import (
+    TEACHING_SECTIONS,
+    AnthologyEntry,
+    anthology_mode,
+)
+from akms_learn.modes.bundle_source import bundle_source_mode
+from akms_learn.modes.outline import outline_mode
+from akms_learn.modes.pitfall import (
+    PITFALL_EDGE_TYPES,
+    STRUCTURED_FIELDS,
+    pitfall_mode,
+)
+from akms_learn.models import (
+    AssessmentView,
+    CodeLinkView,
+    CompilerInfo,
+    LearningEdgeView,
+    LearningNodeView,
+    LearningRequestInfo,
+    LearningSourcePacket,
+    LearningWarning,
+    PacketBody,
+    PitfallView,
+    ReferenceView,
+    SourceInfo,
+)
+from akms_learn.ordering import LEARNING_BUCKETS, order_nodes
+from akms_learn.requests import (
+    LearningRequest,
+    normalize_request,
+    request_hash,
+    to_canonical_dict,
+)
+from akms_learn.section_extraction import (
+    APPROVED_HEADINGS,
+    EXCERPT_MAX_CHARS,
+    ExtractedSection,
+    ExtractionMethod,
+    extract_sections_from_node,
+    extract_sections_from_nodes,
+)
+from akms_learn.sections import APPROVED_SECTIONS, SectionView, extract_sections
+from akms_learn.validation import PacketValidationError, validate_packet
+from akms_learn.warnings import (
+    WarningAccumulator,
+    emit_dangling_reference_warning,
+    emit_missing_section_warning,
+)
+
+__all__ = [
+    # Compiler
+    "STAGES",
+    "CompileResult",
+    "compile_learning_source",
+    # Graph import
+    "GraphSlice",
+    "load_graph",
+    "compute_graph_hash",
+    "fixture_graph",
+    # Ordering
+    "LEARNING_BUCKETS",
+    "order_nodes",
+    # Sections
+    "APPROVED_SECTIONS",
+    "SectionView",
+    "extract_sections",
+    # Node-level section extraction
+    "APPROVED_HEADINGS",
+    "EXCERPT_MAX_CHARS",
+    "ExtractedSection",
+    "ExtractionMethod",
+    "extract_sections_from_node",
+    "extract_sections_from_nodes",
+    # LSP models
+    "LearningSourcePacket",
+    "CompilerInfo",
+    "SourceInfo",
+    "LearningRequestInfo",
+    "PacketBody",
+    "LearningNodeView",
+    "LearningEdgeView",
+    "PitfallView",
+    "CodeLinkView",
+    "AssessmentView",
+    "ReferenceView",
+    "LearningWarning",
+    "LearningRequest",
+    "normalize_request",
+    "request_hash",
+    "to_canonical_dict",
+    "WarningAccumulator",
+    "emit_missing_section_warning",
+    "emit_dangling_reference_warning",
+    "PacketValidationError",
+    "validate_packet",
+    # Domain-pack foundation
+    "CapabilityStatus",
+    "CompanionRole",
+    "DomainPackDescriptor",
+    "DomainPackRegistry",
+    "DomainPackWarning",
+    "LearningCapabilityError",
+    "RuntimeHint",
+    "SourcePackDescriptor",
+    "build_registry_from_paths",
+    "load_descriptor_from_yaml",
+    "load_source_pack_from_yaml",
+    "warn_planned_companion",
+    # Exporters
+    "markdown_export",
+    "bundle_export",
+    "MANIFEST_VERSION",
+    # Structured modes
+    "outline_mode",
+    "anthology_mode",
+    "AnthologyEntry",
+    "TEACHING_SECTIONS",
+    "pitfall_mode",
+    "PITFALL_EDGE_TYPES",
+    "STRUCTURED_FIELDS",
+    "bundle_source_mode",
+    # CLI
+    "main",
+]

akms_learn-0.3.0/src/akms_learn/_code_links.py

@@ -0,0 +1,154 @@
+"""Shared helpers for code-link extraction.
+
+Promoted from ``compiler.py`` and ``modes/implementation_first.py`` to
+remove duplication. Lives at the package
+top level so both the compiler stage and the ``implementation_first`` mode
+can call into the same authoritative implementation.
+
+Surface
+-------
+* :data:`MISSING_SOURCE_PATH_SENTINELS` — frozenset of placeholder strings
+  that count as "no usable source path" (``"", "unknown", "none", "null"``).
+* :func:`is_missing_source_path` — predicate over a raw ``source_path``
+  value; case-insensitive, whitespace-tolerant, None-safe.
+* :func:`coerce_line_range` — best-effort coercion of a node/edge
+  ``line_range`` value into a ``(start, end)`` integer tuple.
+* :func:`build_code_links` — walks ``implements`` edges and emits one
+  :class:`CodeLinkView` per edge. Optionally invokes a missing-source
+  callback so the compiler can emit ``code_mirror_missing_source_path``
+  warnings while the mode keeps its own simpler warning path.
+
+Callers
+-------
+* ``compiler._build_code_links`` thin-wraps :func:`build_code_links`
+  passing the WarningAccumulator-driven callback.
+* ``implementation_first._build_code_references`` uses the no-callback
+  form; it emits ``implementation_anchor_missing_source`` separately
+  via :func:`implementation_first._emit_anchor_missing_source_warnings`.
+
+The module has no LLM imports.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from akms_learn.models import CodeLinkView
+
+__all__ = [
+    "MISSING_SOURCE_PATH_SENTINELS",
+    "is_missing_source_path",
+    "coerce_line_range",
+    "build_code_links",
+]
+
+
+MISSING_SOURCE_PATH_SENTINELS: frozenset[str] = frozenset(
+    {"", "unknown", "none", "null"}
+)
+
+
+def is_missing_source_path(value: Any) -> bool:
+    """Return True if *value* is an unusable placeholder source path.
+
+    Treats ``None``, empty string, and the canonical sentinels
+    (``"unknown"`` / ``"none"`` / ``"null"``) as missing. Comparison is
+    case-insensitive after stripping whitespace.
+    """
+    if value is None:
+        return True
+    text = str(value).strip().lower()
+    return text in MISSING_SOURCE_PATH_SENTINELS
+
+
+def coerce_line_range(value: Any) -> tuple[int, int]:
+    """Best-effort coercion of a node/edge ``line_range`` to ``(start, end)``.
+
+    Returns ``(0, 0)`` for any malformed input (non-list, wrong length,
+    non-integer elements). The placeholder pair is recognised by callers
+    that want to skip uninformative line ranges.
+    """
+    if isinstance(value, (list, tuple)) and len(value) == 2:
+        try:
+            return (int(value[0]), int(value[1]))
+        except (TypeError, ValueError):
+            pass
+    return (0, 0)
+
+
+def build_code_links(
+    edges: tuple[dict[str, Any], ...] | list[dict[str, Any]],
+    nodes_by_id: dict[str, dict[str, Any]],
+    on_missing_mirror_source: Optional[Callable[[str, str], None]] = None,
+) -> list[CodeLinkView]:
+    """Walk ``implements`` edges and emit one :class:`CodeLinkView` per edge.
+
+    Behaviour:
+
+    * One :class:`CodeLinkView` per edge with ``type == "implements"``.
+    * ``source_node_id`` is the edge's ``from`` endpoint.
+    * ``target`` resolves to the target node id (always set when present).
+    * ``relation`` is fixed to ``"implements"``.
+    * ``file_path`` and ``line_range`` come from the target node when the
+      target has a usable ``source_path``; otherwise the fields stay
+      ``None``.
+    * When *on_missing_mirror_source* is supplied AND the target node is a
+      ``code_mirror`` with a missing/sentinel ``source_path``, the callback
+      is invoked once per such edge with ``(mirror_node_id, edge_id)``.
+      The mode-level caller (``implementation_first``) passes ``None`` so
+      it can emit its own ``implementation_anchor_missing_source`` warning
+      via a separate code path.
+
+    The collector is order-stable: edges are processed in the order they
+    arrive in (assumed already sorted by the caller) and the returned list
+    preserves that order.
+    """
+    code_links: list[CodeLinkView] = []
+    for edge in edges:
+        if edge.get("type") != "implements":
+            continue
+
+        source_id = str(edge.get("from") or "")
+        target_id = str(edge.get("to") or "")
+        edge_id = str(edge.get("edge_id") or "")
+
+        target_node = nodes_by_id.get(target_id) or {}
+        target_source_path = target_node.get("source_path")
+        line_range_raw = target_node.get("line_range")
+
+        usable_path: Optional[str] = (
+            None
+            if is_missing_source_path(target_source_path)
+            else str(target_source_path)
+        )
+        usable_line_range: Optional[tuple[int, int]] = None
+        if usable_path is not None and line_range_raw is not None:
+            coerced = coerce_line_range(line_range_raw)
+            if coerced != (0, 0):
+                usable_line_range = coerced
+
+        target_value = target_id or (usable_path or "")
+
+        code_links.append(
+            CodeLinkView(
+                node_id=source_id or target_id or edge_id,
+                source_file=usable_path or "unknown",
+                source_node_id=source_id or None,
+                target=target_value or None,
+                relation="implements",
+                file_path=usable_path,
+                line_range=usable_line_range,
+                mirror_node_id=(
+                    target_id if target_node.get("kind") == "code_mirror" else None
+                ),
+            )
+        )
+
+        if (
+            on_missing_mirror_source is not None
+            and target_node.get("kind") == "code_mirror"
+            and is_missing_source_path(target_source_path)
+        ):
+            on_missing_mirror_source(target_id, edge_id)
+
+    return code_links