class Noir::SpecLineIndex

Overview

Where each key of a structured specification document is declared.

The specification analyzers read their documents through JSON.parse / YAML.parse, and JSON::Any / YAML::Any keep no source positions at all. That is why an OpenAPI scan could say an operation came from openapi.yaml but never which of its 8000 lines — the parser threw the position away before the analyzer saw the node.

This walks the same text a second time with the position-aware pull parsers and records the 1-based line of every mapping key under root, down to max_depth levels. For OpenAPI that is paths -> path -> method, i.e. root: "paths", max_depth: 2, which is exactly the line an operation is declared on.

Only the subtree under root is walked; everything else is skipped without being materialized, so indexing a large document costs a scan of its paths section rather than a second full parse tree.

Mapping keys only. A sequence value is skipped whole, so a document that addresses operations by array position (Postman's nested item) is not served by this and gets no line rather than a guessed one.

Defined in:

utils/spec_line_index.cr

Constant Summary

MAX_CONTENT_BYTES = (64 * 1024) * 1024

A document bigger than this is not indexed. Both walks are streaming, but the index itself is proportional to the number of keys under root, and noir scans untrusted repositories.

SEPARATOR = '\0'

Key paths are flattened into one string so lookups don't allocate an array per query. NUL cannot appear in a JSON/YAML key that the parsers hand back as a scalar, so it is an unambiguous separator.

Constructors

Instance Method Summary

Constructor Detail

def self.empty : SpecLineIndex #

[View source]
def self.json(content : String, root : String | Nil = nil, max_depth : Int32 = 2) : SpecLineIndex #

Index a JSON document. root names the single top-level key whose subtree is indexed; nil indexes the document mapping itself, which is what a document keyed directly by route name needs.


[View source]
def self.new(entries : Hash(String, Int32) = Hash(String, Int32).new) #

[View source]
def self.yaml(content : String, root : String | Nil = nil, max_depth : Int32 = 2) : SpecLineIndex #

Index a YAML document (first document of the stream). See .json for what root means.


[View source]

Instance Method Detail

def empty? : Bool #

[View source]
def entries : Hash(String, Int32) #

[View source]
def line(keys : Array(String)) : Int32 | Nil #

[View source]
def line(*keys : String) : Int32 | Nil #

1-based line the given key path is declared on, or nil when the document has no such key at an indexed depth.


[View source]