Markdown extractor: code-span references promised in the docstring are not implemented · Issue #3561 · Graphify-Labs/graphify · GitHub
Skip to content

Markdown extractor: code-span references promised in the docstring are not implemented #3561

Closed

Description

@AstroMined

graphify/extractors/markdown.py (extract_markdown, on v8 at fe66389 and in the 0.9.58 wheel)
documents this edge:

heading --references--> other node (when backtick `Name` matches a known pattern)

Nothing implements it. The extractor emits page and heading nodes, contains edges, and
references edges only for inline, reference-style and wiki links to other markdown files. A code
span in a heading or body line never produces an edge, so an AST build has no document-to-code edge
at all.

Reproduction (0.9.58):

d=$(mktemp -d)
printf 'class Widget:\n    pass\n' > $d/widget.py
printf '# Doc\n\n## `Widget`\n\nThe `Widget` class.\n' > $d/doc.md
python -c "from pathlib import Path; from graphify.extract import extract; \
r = extract([Path('$d/widget.py'), Path('$d/doc.md')]); \
print(sum(1 for e in r['edges'] if e.get('relation') == 'references'))"

prints 0.

Proposed fix, implemented and tested on a fork branch (PR to follow):

  1. extract_markdown collects inline code spans outside fences and frontmatter as raw_calls
    tagged language: "markdown", owned by the enclosing heading (the page node before the first
    heading). Forms: bare Name, Name(), dotted pkg.Name, and path.py::Name(::Name)*.
  2. A markdown_mentions language resolver (registered through register_language_resolver, so it
    runs after the id-remap passes) resolves them. The path::Symbol form matches the cited file
    doc-relative, then exact, then as a unique path suffix, and walks contains/method edges to the
    symbol: EXTRACTED 1.0. A bare name resolves only when exactly one callable code node carries the
    label: INFERRED 0.95. Ambiguous names, builtins, missing files and non-callable matches emit
    nothing.
  3. The shared cross-file call pass skips markdown raw_calls, so prose never emits calls edges and
    document nodes stay out of call resolution.
  4. The docstring is corrected.

Results on the branch: the six new tests pass; the existing suite is unchanged (5,569 passed, 14
skipped; the eight failures, four test_backup_* in tests/test_export.py and four
test_pathless_postgres_extract_initializes_empty_detection cases in tests/test_extract_cli.py,
fail identically on clean v8). A dry run over a 1,581-document, 11,297-symbol Python repo produced 3,532 document-to-code
references edges (3,409 INFERRED, 123 EXTRACTED) from 10,809 mentions; 985 ambiguous names were
skipped. The only recurring false positive found was a prose word (source) matching a same-named
test fixture function.

Activity

  1. safishamsi commented on Sep 15, 2026

    @safishamsi
    Member

    Fixed in v0.9.62 (on PyPI) via #3562, thanks @AstroMined. Thanks for the report!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions