How to Report a Bug in Graphify: Complete Guide with Examples

To report a bug in Graphify, collect the input file and the specific cache entry from graphify-out/cache/, then submit a GitHub issue containing the reproduction command, observed behavior, and expected results.

Graphify is an open-source extraction and analysis tool maintained by Graphify-Labs. When the parser fails to capture nodes, generates incorrect edges, or crashes on specific inputs, submitting a detailed bug report ensures maintainers can reproduce the issue efficiently. Understanding how to report a bug in Graphify according to the project's official guidelines—documented in README.md at line 837—accelerates the triage process.

Required Artefacts for a Complete Bug Report

The Graphify maintainers require two critical files to investigate extraction failures: the original input file and the corresponding cache entry generated by the core extraction logic.

Input File and Cache Entry

Every bug report must include:

• The input file (source code, PDF, image, etc.) that triggers the bug
• The cache entry located under graphify-out/cache/ (e.g., graphify-out/cache/<hash>.json). This file contains the intermediate representation generated by graphify/out/__init__.py and is essential for reproducing parsing errors.

As stated in the README.md: "Extraction bugs — open an issue with the input file, the cache entry (graphify-out/cache/), and what was missed or wrong."

Environment Context

Include your operating system, Python version, and Graphify version (run graphify --version). If the bug involves a specific language extractor (e.g., Rust, Objective-C), mention this explicitly, as different extractors may trigger unique code paths in the extraction pipeline.

Step-by-Step Guide to Reporting Bugs

Follow this workflow to ensure your issue contains actionable information for the maintainers:

1. Gather artefacts: Locate your input file and the cache file created in graphify-out/cache/ after running the extraction command. The cache contains the serialized graph state produced by the extraction engine.

2. Open a GitHub issue: Navigate to https://github.com/Graphify-Labs/graphify/issues and click "New issue". Select the bug report template if available.

3. Complete the description:

   • Brief summary: One sentence describing the problem
   • Steps to reproduce: The exact command executed (e.g., graphify extract ./file.ts --lang ts)
   • Observed behavior: Error messages or incorrect graph output
   • Expected behavior: The correct node structure or successful extraction
   • Attachments: Upload both the input file and the cache entry

4. Add technical context: Reference relevant source files if known. Bugs involving duplicate node IDs often relate to graphify/ids.py, while cache staleness issues connect to graphify/watch.py. API-related bugs may involve graphify/serve.py.

5. Submit: Post the issue for triage. The maintainers will analyze the cache entry to trace the issue through the extraction pipeline.

Bug Report Templates and Examples

Use these concrete examples to structure your report according to the source code requirements.

Example 1: Missing TypeScript Nodes

When class or method nodes fail to appear in the output:

# Command you ran

graphify extract ./examples/bad.ts --lang ts

# Expected: nodes for class `Foo` and method `bar`

# Observed: only the file node appears

Attachments: Include bad.ts and graphify-out/cache/8f3c9e…json.

Example 2: PDF Extraction Failure

When processing documents triggers encoding errors:

graphify extract ./docs/report.pdf --lang pdf

# Expected: a `document` node with extracted text

# Observed: the command fails with `UnicodeDecodeError`

Attachments: Include report.pdf and graphify-out/cache/d2a4b1…json.

Summary

• Always attach the input file and the corresponding graphify-out/cache/ entry to every bug report, as required by the guidelines in README.md at line 837.
• Structure your issue with reproduction steps, observed behavior, and expected behavior to help maintainers trace the logic in graphify/out/__init__.py.
• Reference the source: Key files like graphify/ids.py (node ID generation) and graphify/watch.py (cache resolution) help maintainers locate the root cause.
• Check translations: The Chinese translation of the guidelines exists in docs/translations/README.zh-CN.md at line 222.

Frequently Asked Questions

What should I do if Graphify doesn't create a cache file?

If the crash occurs before cache generation in graphify-out/cache/, submit the input file and the complete error traceback. Include your environment details and the exact command used. However, most extraction bugs require the cache entry for analysis, so verify the cache directory exists after the failure, as the core extraction logic in graphify/out/__init__.py typically generates these files before final output.

Can I report bugs for the HTTP API server?

Yes. Bugs affecting the server endpoints should reference graphify/serve.py and include the HTTP request payload along with the server logs. If the issue involves cached data served via the API, include the relevant cache entry from graphify-out/cache/ to help reproduce the serialization error.

How do I report bugs in watch mode?

For issues specific to file watching or incremental updates, mention graphify/watch.py in your report. Include steps showing how the cache becomes stale or fails to update when source files change, along with the cache entries before and after the observed behavior. This helps maintainers debug the cache resolution logic.

Where are the official bug reporting guidelines documented?

The primary guidelines reside in README.md at line 837 of the Graphify-Labs/graphify repository. A Chinese translation is available in docs/translations/README.zh-CN.md at line 222. Both documents explicitly require the input file and cache entry for all extraction bug reports.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}