microsoft / microsoft/language-server-protocol

LSIF spec could use some extra clarity around embedded contents

Open
#1,139 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification lsif
Dominant language
TypeScript
Stars
13k
Forks
1k
Avg merge
6d 1h
Merged PRs (30d)
10

Description

The LSIF spec states that the contents of a file included in an LSIF index is encoded base64:

It can be valuable to embed the contents of a document or project file into the dump as well. For example, if the content of the document is a virtual document generated from program meta data. The index format, therefore, supports an optional contents property on the document and project vertex. If used the content needs to be base64 encoded.

Given base64 is a encoding of a binary stream, this implies that there's a text encoding question. So some questions:

  1. Should the binary stream be the raw file on disk, in whatever text encoded form it is? This then means it's the responsibility of any consumer to do encoding sniffing which may come to a different conclusion (and therefore different contents) than the indexer. The alternative is the indexer re-encodes in some preferred/specified text encoding prior to the base64 encoding, although that still creates other fun questions around binary file inputs to compilers.
  2. For files that have no "native" encoding because the indexer generated them directly in memory, which encoding should be chosen as a preferred choice?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the “Embedding contents” section in specification.md, linked from the issue. Review how the LSIF specification describes base64-encoded contents and determine what encoding questions the text leaves unresolved. Done means the specification clearly defines the expected encoding for disk files and generated in-memory contents.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.