@mrclrchtr/supi-tree-sitter 9.1.2 → 11.0.0

package/README.md

@@ -38,27 +38,60 @@ It does **not** register pi tools or commands on its own.
 
 Coordinates in the library APIs use **1-based** line and character columns. Character positions use UTF-16 code units. Relative paths resolve from the session cwd, and a leading `@` on file paths is stripped.
 
-## Supported file families
+## Language support matrix
 
-- JavaScript / TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`)
-- Python (`.py`, `.pyi`)
-- Rust (`.rs`)
-- Go (`.go`)
-- C / C++ (`.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++`)
-- Java (`.java`)
-- Kotlin (`.kt`, `.kts`)
-- Ruby (`.rb`, `.gemspec`)
-- Bash / shell (`.sh`, `.bash`, `.zsh`, `.ksh`)
-- HTML (`.html`, `.htm`, `.xhtml`)
-- R (`.r`)
-- SQL (`.sql`)
-- LaTeX (`.tex`, `.sty`, `.cls`)
+The package bundles 16 grammars for 38 file extensions. All listed extensions support parsing, point-node inspection, and custom Tree-sitter queries without an LSP server. Grammar selection uses the file extension without case sensitivity, not a shebang.
 
-Outline collection supports every listed family. HTML outlines list elements with a non-empty `id` attribute. SQL outlines list `CREATE` declarations and their first-level table and type members. LaTeX outlines list section headings and command, environment, label, acronym, glossary-entry, and color definitions.
+**Yes** means that a built-in extractor or query exists. **No** means that the operation is not implemented for that grammar. Parser support does not guarantee complete extraction of every language construct.
 
-Import collection supports JavaScript, TypeScript, TSX, and LaTeX. LaTeX imports include package, class, source, and bibliography directives. Export collection supports JavaScript, TypeScript, and TSX only. Call-site collection supports every listed family except HTML, SQL, and LaTeX. LaTeX does not support export collection, callee queries, or call-site collection. The LaTeX grammar does not parse `.bib` files.
+| Language / grammar | File extensions | Outline | Imports | Exports | Call sites / callees |
+|---|---|---|---|---|---|
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | Yes | Yes | Yes | Yes |
+| TypeScript | `.ts`, `.mts`, `.cts` | Yes | Yes | Yes | Yes |
+| TSX | `.tsx` | Yes | Yes | Yes | Yes |
+| Python | `.py`, `.pyi` | Yes | Yes | No | Yes |
+| Rust | `.rs` | Yes | Yes | No | Yes |
+| Go | `.go` | Yes | Yes | No | Yes |
+| C | `.c`, `.h` | Yes | Yes | No | Yes |
+| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++` | Yes | Yes | No | Yes |
+| Java | `.java` | Yes | Yes | No | Yes |
+| Kotlin | `.kt`, `.kts` | Yes | No | No | Yes |
+| Ruby | `.rb`, `.gemspec` | Yes | No | No | Yes |
+| Bash | `.sh`, `.bash`, `.zsh`, `.ksh` | Yes | No | No | Yes |
+| HTML | `.html`, `.htm`, `.xhtml` | Yes | No | No | No |
+| R | `.r` | Yes | No | No | Yes |
+| SQL | `.sql` | Yes | No | No | No |
+| LaTeX | `.tex`, `.sty`, `.cls` | Yes | Yes | No | No |
 
-The Go and Ruby grammars do not parse Go module manifests or ERB templates. `supi-lsp` still handles them semantically. For a bulk scan, use `getStructuralSearchSupportedExtensions(operation)`. Parser support does not mean that each operation is supported.
+For a bulk scan, use `getStructuralSearchSupportedExtensions(operation)`. It returns operation-specific extensions: 38 for `outline`, 25 for `imports`, 8 for `exports`, and 31 for `call-sites`. It does not accept `callees` or public search-kind names.
+
+### Mapping to Code Intelligence search
+
+[`code_find` in AST mode](../supi-code-intelligence/README.md#language-support) uses these library operations:
+
+| `code_find` kind | Structural operation | Match source |
+|---|---|---|
+| `definition` | `outline` | Extracted declaration names |
+| `type`, `interface`, `class`, `method`, `enum` | `outline` | Declaration names filtered by outline kind |
+| `import` | `imports` | Written import/source targets, not local aliases or resolved files |
+| `export` | `exports` | Exported names |
+| `call` | `call-sites` | Written call names, not symbol identity |
+
+The `type` filter accepts `class`, `interface`, `type`, `enum`, `struct`, `union`, `record`, `object`, and `concept`. The other kind filters require an exact common outline kind. Not every grammar produces every kind. Results retain `nativeKind` separately. For example, Rust traits use the common `interface` filter but retain `trait`; Go structs retain `struct`, and Java records retain `record`. These do not become `class` results.
+
+### Extraction limits
+
+- TS/JS, Python, Java, Go, Rust, and C/C++ outlines include nested named declarations and members. They are not complete indexes of local variables, parameters, or anonymous expressions. Other languages retain their existing extraction depth. HTML outlines list only elements with non-empty `id` attributes. SQL outlines list supported `CREATE` declarations and first-level table/type members. LaTeX outlines list section headings and selected command, environment, label, acronym, glossary-entry, and color definitions.
+- JavaScript-family imports collect `import` statements, not CommonJS `require()` calls. Exports collect file-level `export` statements, including TypeScript `export =`; they do not collect `module.exports` assignments or nested namespace exports. An eligible `.cjs` file can therefore return no imports or exports.
+- Python imports retain `import`/`from` module targets, including relative prefixes. Java imports retain ordinary/static targets. Go imports retain single/grouped paths. Rust imports retain explicit `use` paths, `extern crate`, and external `mod` names; inline module bodies are not imports. C/C++ imports retain literal quoted and angle-bracket include targets. Grouped paths use explicit syntax only; no files or bindings are resolved. Conditional directives are written evidence, not proof of active dependencies. Dynamic loaders, computed targets, and C++20 module imports remain outside extraction support.
+- LaTeX imports include package, class, source, and bibliography directives. Bibliography directives can refer to `.bib` files, but the grammar does not parse those files.
+- Call-site and callee queries use syntax, not resolved symbol identity. Distinct sites have source ranges; repeated names on one line are not merged. Rust macro invocations are syntax evidence, not expanded calls. JSX tags are not call expressions. Library callee queries work without LSP, but new `code_graph` targets require semantic readiness in Code Intelligence.
+- `.jsx` uses JavaScript; `.tsx` uses the separate TSX grammar. `.h` uses C by default. An explicit session association can select C++ without changing the supported suffix set. `.zsh` and `.ksh` use Bash; this is not complete support for those shell dialects.
+- Go module manifests (`.mod`), Ruby ERB templates (`.erb`), and BibTeX (`.bib`) have [built-in LSP routes](../supi-lsp/README.md#built-in-route-matrix), but no AST grammar. Unlisted extensions, including JSON, YAML, TOML, and CSS, have no grammar. Custom LSP configuration does not add one.
+
+A recovered parse returns `partial` with usable data, a reason, and available syntax-error ranges. Callers must preserve that state instead of interpreting it as complete absence or discarding the data. `canParse()` remains a parseability check, not a claim that syntax or extraction is complete.
+
+Sources: [extension and grammar map](src/language.ts), [operation support](src/operation-support.ts), [call-site queries](src/tool/call-sites.ts), [callee queries](src/tool/callees.ts), and [Code Intelligence kind filters](../supi-code-intelligence/src/analysis/search/pattern-analysis.ts). Regression tests cover [grammar mappings](__tests__/language.test.ts), [operation eligibility](__tests__/operation-support.test.ts), and [call-site queries](__tests__/call-site-languages.test.ts).
 
 ## Architecture
 
@@ -97,6 +130,19 @@ const callees = await session.calleesAt("src/index.ts", 42, 10);
 await session.dispose();
 ```
 
+For C-family paths, direct library callers can pass ordered rules:
+
+```ts
+const session = createTreeSitterSession("/project", {
+  fileAssociations: [
+    { pattern: "vendor/**/*.h", language: "c" },
+    { pattern: "**/*.h", language: "cpp" },
+  ],
+});
+```
+
+The first match wins; patterns are case-sensitive project-relative globs. Without rules, the extension map stays unchanged. Direct callers own configuration trust. The Code Intelligence workspace host reads trusted project rules and supplies the same snapshot to Tree-sitter and LSP. This library does not read SuPi configuration on its own.
+
 ## Structural performance baseline
 
 Run the stable outline fixture on the same machine and dependency versions:

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/picomatch/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017-present, Jon Schlinkert.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.