@cesarandreslopez/occ 0.9.3 → 0.11.0

package/skills/occ/reference/code.md

@@ -1,7 +1,8 @@
 # Code exploration for agents
 
-`occ code` builds an in-memory code graph (no database, no daemon) for JS/TS,
-Vue SFC, and Python. Shared flags on every `code` subcommand: `--path
+`occ code` builds an in-memory code graph (no database, no daemon) for JS/TS
+and Vue SFC (type-accurate) plus Python, Go, Rust, Java, C/C++, C#, Kotlin,
+Scala, Swift, Ruby, and PHP (tree-sitter). Shared flags on every `code` subcommand: `--path
 <repo-root>` (default cwd), `--format json`, `-o <file>`, `--exclude-dir`,
 `--no-gitignore`, `--content-mode none|excerpt|full`, `--max-file-size-bytes
 <n>`, `--max-lines <n>`.
@@ -41,6 +42,38 @@ occ code map --path . --changed-from main --map-tokens 4096   # diff-focused map
 
 All accept `--limit <n>` (default 50) and `--format json`.
 
+## Source reads — `occ code source`
+
+Use `source` when you already know the symbol and need its exact body without
+reading the whole file. Prefer this for named symbols; use `rg`/shell reads for
+text, config, and quick facts.
+
+```bash
+occ code map --path . --map-format json --map-tokens 4096 -o map.json
+occ code source --path . --node-id "<nodeId>" --format json
+occ code source bootstrap --path . --file src/main.ts --type function --format json
+```
+
+JSON repo-map symbols include `nodeId`, `endLine`, and `containerName`. The
+current node-id contract is OCC's existing graph id derived from the indexed
+node: `<type>:<absolute-path>:<name>:<line>[:<containerName>]`. The line number
+is part of the address, so ids can change after edits; re-run `code map` or
+`code find name` after moving a symbol.
+
+## Syntax checks — `occ code check`
+
+Use `check` as a lightweight post-edit parse gate before wider tests. It supports
+TS/JS, Vue SFCs, Python, and the vendored tree-sitter languages (Go, Rust, Java,
+C/C++, C#, Kotlin, Scala, Swift, Ruby, PHP); unsupported files exit 0 with
+`status: "unsupported"` so they do not fail CI accidentally.
+
+```bash
+occ code check src/main.ts --format json
+occ code check src/App.vue --format json
+```
+
+`occ code check` exits nonzero only when `valid` is `false`.
+
 ## Relationships — `occ code analyze <kind>`
 
 - `occ code analyze calls <fn>` — what a function calls (outgoing).
@@ -66,4 +99,44 @@ occ code history buildRepoMap --format json                 # git line history f
 ## Full index — `occ code index`
 
 Build/dump the full codebase index (files, symbols, edges, capabilities). Heavy;
-prefer `map`/`find`/`analyze` for targeted questions.
+prefer `map`/`find`/`analyze` for targeted questions. Each `files[].symbols[]`
+entry carries a `nodeId`, so a consumer can jump from a file symbol straight to
+its graph node (and to `occ code source --node-id <id>`) without scanning
+`nodes`.
+
+## Programmatic surface — for long-running hosts
+
+Editor/agent integrations that embed `occ` — holding an index or a
+`CodeQuerySession` across turns instead of shelling out per call — have
+in-process equivalents for the verbs above, plus a few probes with no CLI:
+
+- **`searchSymbols(index, query, { limit, kinds, pathFilter })`** /
+  `session.searchSymbols(...)` — fuzzy symbol search across name,
+  container-qualified name, and file path. Each result carries a `score`, the
+  matched `positions`/`span` (for highlighting), and a `nodeId` for a follow-up
+  source read. The corpus is memoized per index, so repeated queries in a
+  long-lived host pay the build once. Facade: `createOcc().code.searchSymbols`.
+  From the shell, reach for `occ code find` instead.
+- **`buildCodeContext(index)`** / `session.projectContext()` — project a full or
+  slim index down to per-file exported symbols, a deduplicated local import
+  graph, and external dependency roots. Pure and synchronous; the shape hosts
+  hand to a model or a graph view. Facade: `createOcc().code.context`.
+- **`buildChangedRepoMap(index, { changed: { base, head } | { staged: true }, ...mapOptions })`**
+  — the `--changed-from` map on the API: changed files join the focus set and
+  admitted entries carry `changed`/`churn`. `toRepoMapChangeContext` /
+  `stampRepoMapChanges` are exported for callers that already hold a diff
+  summary. Facade: `createOcc().code.mapChanged`.
+- **`store.peekMetadata()` / `store.isFresh()`** — probe a persisted
+  `CodeIndexStore` without deserializing or parsing. `peekMetadata()` returns the
+  on-disk metadata (available before the first `getSession()` of a process);
+  `isFresh()` stat-diffs the working tree against the persisted manifest
+  (`added`/`modified`/`deleted` counts). Both validate the cache entry belongs to
+  this repo, options, and occ version — use them to decide whether to rebuild
+  before serving a session.
+- **`health().features`** — a map of stable feature identifiers (e.g.
+  `code.searchSymbols`, `store.isFresh`, `code.map.changed`). Feature-detect
+  against it (`health.features?.['store.isFresh'] === true`) instead of
+  `typeof`-probing when a host must support multiple occ versions.
+
+`createCodeQuerySession(options, onProgress?, signal?)` and
+`session.refresh(onProgress?, signal?)` accept an `AbortSignal` for cancellation.

package/skills/occ/reference/commands.md

@@ -33,11 +33,13 @@ tabular|json`, `-o <file>`, and `--ci`.
 
 - `occ table inspect <file>` — Extract structured table data from DOCX, XLSX, PPTX, ODT, or ODP documents.
 
-## `occ code` — Explore code structure with first-class JS/TS and Python support
+## `occ code` — Explore code structure (type-accurate JS/TS + Vue SFC, tree-sitter for 12 more languages)
 
 - `occ code map` — Token-budgeted, importance-ranked repo map (top symbol signatures per file).
 - `occ code pack` — Token-budgeted, importance-ranked pack (file content, optionally compressed).
 - `occ code index` — Build the full codebase index (files, symbols, edges, capabilities).
+- `occ code source <name>` — Read one symbol body by node id (`--node-id`) or disambiguated name.
+- `occ code check <file>` — Check a file's syntax without a language server (exits nonzero only when invalid).
 - `occ code find name <name>` — Find code elements by exact name.
 - `occ code find pattern <pattern>` — Find code elements by substring pattern.
 - `occ code find type <nodeType>` — List all nodes of a given type.

package/vendor/tree-sitter/c/tags.scm

@@ -0,0 +1,4 @@
+(function_definition) @definition.function
+(struct_specifier) @definition.class
+(enum_specifier) @definition.enum
+(call_expression) @reference.call

package/vendor/tree-sitter/c-sharp/tags.scm

@@ -0,0 +1,6 @@
+(method_declaration) @definition.method
+(constructor_declaration) @definition.method
+(class_declaration) @definition.class
+(interface_declaration) @definition.interface
+(invocation_expression) @reference.call
+(object_creation_expression) @reference.call

package/vendor/tree-sitter/cpp/tags.scm

@@ -0,0 +1,5 @@
+(function_definition) @definition.function
+(class_specifier) @definition.class
+(struct_specifier) @definition.class
+(enum_specifier) @definition.enum
+(call_expression) @reference.call

package/vendor/tree-sitter/go/tags.scm

@@ -0,0 +1,4 @@
+(function_declaration) @definition.function
+(method_declaration) @definition.method
+(type_declaration) @definition.type
+(call_expression) @reference.call

package/vendor/tree-sitter/java/tags.scm

@@ -0,0 +1,7 @@
+(method_declaration) @definition.method
+(constructor_declaration) @definition.method
+(class_declaration) @definition.class
+(interface_declaration) @definition.interface
+(enum_declaration) @definition.enum
+(method_invocation) @reference.call
+(object_creation_expression) @reference.call

package/vendor/tree-sitter/kotlin/tags.scm

@@ -0,0 +1,4 @@
+(function_declaration) @definition.function
+(class_declaration) @definition.class
+(object_declaration) @definition.class
+(call_expression) @reference.call

package/vendor/tree-sitter/php/tags.scm

@@ -0,0 +1,8 @@
+(function_definition) @definition.function
+(method_declaration) @definition.method
+(class_declaration) @definition.class
+(interface_declaration) @definition.interface
+(trait_declaration) @definition.class
+(function_call_expression) @reference.call
+(member_call_expression) @reference.call
+(scoped_call_expression) @reference.call

package/vendor/tree-sitter/python/tags.scm

@@ -0,0 +1,3 @@
+(function_definition) @definition.function
+(class_definition) @definition.class
+(call) @reference.call

package/vendor/tree-sitter/ruby/tags.scm

@@ -0,0 +1,5 @@
+(method) @definition.method
+(singleton_method) @definition.method
+(class) @definition.class
+(module) @definition.class
+(call) @reference.call

package/vendor/tree-sitter/rust/tags.scm

@@ -0,0 +1,5 @@
+(function_item) @definition.function
+(struct_item) @definition.class
+(enum_item) @definition.enum
+(trait_item) @definition.interface
+(call_expression) @reference.call

package/vendor/tree-sitter/scala/tags.scm

@@ -0,0 +1,5 @@
+(function_definition) @definition.function
+(class_definition) @definition.class
+(object_definition) @definition.class
+(trait_definition) @definition.interface
+(call_expression) @reference.call

package/vendor/tree-sitter/swift/tags.scm

@@ -0,0 +1,4 @@
+(function_declaration) @definition.function
+(class_declaration) @definition.class
+(protocol_declaration) @definition.interface
+(call_expression) @reference.call