com.blockether.vis.internal.foundation.editing.index — com.blockether/vis 0.1.5

Structural INDEX: a high-level, line-ranged skeleton of a source file produced via tree-sitter (com.blockether/tree-sitter-language-pack, which sources Clojure from our own grammar fork).

Every item carries FULL anchors — the same <lineno>:<hash> anchors cat emits and patch consumes — for its first and last line, so you can replace a whole definition straight from the index with one patch([{path P, from_anchor start, to_anchor end, replace …}]), no intermediate cat. Each line is:

<kind> <name> <signature> @<start-anchor>..<end-anchor>

e.g.

class Greeter @3:a1b..7:c2d function hello @6:1b2..7:c2d function main @9:3c4..10:5d6

Read it BEFORE cat: a cheap map of a file so you jump straight to the right range (and its anchors) instead of reading the whole file.

Requiring this namespace also requires the native resolver, which selects the right per-platform FFI library at runtime.

code-language clj

(code-language path)

The tree-sitter language for path IFF it is a vetted CODE language (code-languages) — else nil. Use this (not detect-language) wherever a syntax-error refusal must be meaningful: prose / markup / data / .log / extensionless files all return nil, so they're never falsely guarded.

code-languages clj

Curated allowlist of tree-sitter languages vis treats as CODE — where a parse ERROR means a genuinely broken file, worth refusing an edit over. Deliberately EXCLUDES the pack's prose / markup / loose grammars (vimdoc — remember .txt maps to it! — markdown, rst, csv, html, xml, ini …) that carry error nodes on normal content and would fire false positives. Real programming languages plus the STRICT structured-config formats (json/yaml/toml). This is the vetted subset the syntax guard runs on; extend it as vis takes on more languages.

definitions clj

(definitions source language)

(definitions source language name)

The DATA behind file-skeleton: every definition in source (parsed as language), flattened across nesting, as [{:name :kind :visibility :signature :doc :anchor :end-anchor :depth} …] where the def's span is patch-ready lineno:hash anchors — the SOLE position (no redundant start/end line; patch/anchor->line recovers the number). So struct_index → patch needs no re-cat. With name, only the definitions with that exact name (there may be several — same name in different scopes). Empty when the language is unsupported or nothing structural was found.

detect-language clj

(detect-language path)

tree-sitter language name for path (by extension/shebang), or nil. NOTE: the pack recognizes HUNDREDS of grammars, including prose/markup — .txt maps to vimdoc (Vim :help files), .md→markdown, .csv→csv — which parse WITH error nodes on ordinary content. For 'is a syntax error meaningful here?' use code-language, not this.

Falls back to extra-extension->language (currently .edn→clojure) ONLY when the pack returns nil, covering Clojure-family extensions the pack's table omits so their files still get structural editing.

file-index clj

(file-index path)

(file-index path source)

(file-index path source range)

Maki-style structural INDEX of path, produced in a SINGLE tree-sitter pass:

{:language str :line-count int :skeleton str ; header + imports + nested definitions, all anchored :definitions [row …] ; machine rows (== definitions) — anchor/end-anchor :imports [row …]} ; machine import rows, each anchored

nil when the language is unsupported, or the file has no imports and nothing structural. source may be passed to avoid a re-read (e.g. unsaved buffers). range narrows the index to the imports and TOP-LEVEL definitions whose span intersects it — either a SINGLE 1-based inclusive [lo hi] (either order) or a COLLECTION of such windows [[lo hi] …] (a def kept when it hits ANY window). Each kept def's own children stay intact; :line-count still reports the WHOLE file. With a range set, a hit-nothing window still returns a (header-only) index rather than nil, so the caller can tell 'empty window' from 'unsupported'.

file-skeleton clj

(file-skeleton path)

(file-skeleton path source)

Skeleton string for path (items + line ranges + full start..end anchors), or nil when the language is unsupported or nothing structural was found. source may be passed to avoid a re-read (e.g. for unsaved buffers).

node-span clj

(node-span source language target kind)

0-based inclusive [start-line end-line] of the TOP-LEVEL structural node named target (optionally narrowed by kind, case-insensitive), or nil if not found. Used by the structural move op to extract a node's exact source text by name.

pack-kind clj

(pack-kind kind)

Inverse of canonical-kind: map a terse :kind (fn) BACK to the pack's raw StructureKind name (function) so struct_patch's kind disambiguator matches the pack. Unknown/other kinds pass through unchanged; nil/blank → nil.

resolve-edit-kind clj

(resolve-edit-kind source language target kind)

The raw StructureKind name to hand the pack engine's name+kind locator for target, made resilient to an over-specific or mismatched kind (e.g. the source def-form head defdescribe/deftest, which the pack reports as fn):

• no kind → nil (locate by name alone);
• kind matches a def named target → that pack kind (normal disambiguation);
• kind matches NO def named target, yet exactly ONE def carries that name → nil, so a wrong/over-specific kind never blocks an unambiguous by-name edit;
• otherwise the pack kind unchanged (let the engine report the real miss or ambiguity).