@cesarandreslopez/occ 0.9.3 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesarandreslopez/occ",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Office Cloc and Count — document metrics, structure extraction, content inspection, and code exploration for real repositories",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -108,6 +108,14 @@
       "types": "./dist/src/code/diff.d.ts",
       "default": "./dist/src/code/diff.js"
     },
+    "./code/source": {
+      "types": "./dist/src/code/source.d.ts",
+      "default": "./dist/src/code/source.js"
+    },
+    "./code/check": {
+      "types": "./dist/src/code/check.d.ts",
+      "default": "./dist/src/code/check.js"
+    },
     "./git": {
       "types": "./dist/src/git/index.d.ts",
       "default": "./dist/src/git/index.js"
@@ -282,6 +290,12 @@
       "code/diff": [
         "dist/src/code/diff.d.ts"
       ],
+      "code/source": [
+        "dist/src/code/source.d.ts"
+      ],
+      "code/check": [
+        "dist/src/code/check.d.ts"
+      ],
       "git": [
         "dist/src/git/index.d.ts"
       ],
@@ -386,7 +400,8 @@
   "files": [
     "dist/",
     "scripts/postinstall.js",
-    "skills/"
+    "skills/",
+    "vendor/tree-sitter/"
   ],
   "publishConfig": {
     "access": "public"
@@ -415,6 +430,7 @@
     "pdf-parse": "^1.1.4",
     "turndown": "^7.2.2",
     "typescript": "^5.9.3",
+    "web-tree-sitter": "^0.26.10",
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "zod": "^4.3.6"
   },

package/skills/occ/SKILL.md

@@ -7,13 +7,14 @@ description: >-
   with "occ describe" and "occ workspace analyze"; office-document and table
   triage for DOCX, PDF, XLSX, PPTX, ODT, ODS, and ODP with "occ doc inspect",
   "occ sheet inspect", "occ slide inspect", and "occ table inspect"; and code
-  exploration for JS/TS, Vue SFC, and Python with "occ code map", "occ code
-  pack", "occ code find", "occ code analyze", "occ code diff", and "occ git
-  diff". Reach for it whenever you need to understand a codebase or a set of
+  exploration for JS/TS, Vue SFC, Python, Go, Rust, Java, C/C++, Kotlin, and
+  other tree-sitter-backed languages with "occ code map", "occ code source",
+  "occ code check", "occ code find", "occ code analyze", "occ code diff", and
+  "occ git diff". Reach for it whenever you need to understand a codebase or a set of
   office files without burning context reading everything, or whenever the user
   mentions occ.
 metadata:
-  version: 0.9.3
+  version: 0.10.0
 license: MIT
 ---
 
@@ -30,6 +31,10 @@ Design principles to lean on:
 - **Token-budgeted** — `occ code map/pack` and `occ code diff` accept `--map-tokens <n>`
   (and the root scan accepts `--token-budget <n>`). Pair with `--tokenizer o200k_base`
   (or `cl100k_base`) for an _exact_ BPE budget instead of the default heuristic estimate.
+- **Structural for named symbols/relations, shell for text/config/quick facts** — use
+  `occ code map`, `occ code find name`, `occ code source`, and `occ code analyze callers`
+  when the target is a symbol, call path, class tree, or import relationship. Use `rg`,
+  `grep`, or direct file reads for strings, config keys, generated files, and one-off facts.
 - **Stream large output to a file** — for big maps/packs/analyses, add `-o <file>` and
   read it back selectively rather than flooding the conversation.
 
@@ -59,6 +64,8 @@ Run `occ --help` or `occ <group> --help` to see every flag.
 | Pull file _contents_ within a token budget              | `occ code pack --path . --map-tokens 8000 --tokenizer o200k_base -o pack.md`   | [reference/code.md](reference/code.md)           |
 | Find a symbol / concept (best-effort)                   | `occ code find fused "<query>" --format json`                                  | [reference/code.md](reference/code.md)           |
 | Find an exact symbol by name or type                    | `occ code find name <Name> --format json`                                      | [reference/code.md](reference/code.md)           |
+| Read one known symbol body                              | `occ code source --node-id <nodeId> --format json`                             | [reference/code.md](reference/code.md)           |
+| Check parse syntax after edits                          | `occ code check <file> --format json`                                          | [reference/code.md](reference/code.md)           |
 | See who calls X / what X calls                          | `occ code analyze callers <fn>` · `occ code analyze calls <fn>`                | [reference/code.md](reference/code.md)           |
 | Inspect imports / module coupling                       | `occ code analyze deps <target>` · `occ code analyze coupling <target>`        | [reference/code.md](reference/code.md)           |
 | See which _symbols_ changed in a diff                   | `occ code diff --base <ref> --map-tokens 4096 --format json`                   | [reference/code.md](reference/code.md)           |
@@ -67,11 +74,15 @@ Run `occ --help` or `occ <group> --help` to see every flag.
 ## Recommended agent workflows
 
 - **Land in a new repo:** `occ describe . --format json` → `occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md`, read the map, then drill in with `occ code find` / `occ code analyze`.
+- **Read a symbol precisely:** `occ code map --map-format json` → take `nodeId` from the relevant symbol → `occ code source --node-id <nodeId> --format json`.
+- **Find name then read:** `occ code find name TypeName --format json` → if one match, `occ code source --node-id <nodeId>`; if ambiguous, rerun with `--file` or `--type`.
+- **Trace impact:** `occ code analyze callers targetFn --format json` before broad text search; use candidates and valid node kinds from ambiguous output to refine the query.
+- **Post-edit syntax gate:** run `occ code check <changed-file> --format json`; it exits nonzero only when `valid` is `false`.
 - **Review a change:** `occ git changed` → `occ code diff --base <base> --format json` for symbol-level scope → `occ git diff --patch --map-tokens 4096` for a bounded patch.
 - **Process a document drop:** `occ <dir> --format json` for the inventory → `occ doc/sheet/slide inspect --format json` per file → `occ table inspect` to pull tabular data → read only what matters.
 
 ## Notes
 
 - For the full flag list of every command, read [reference/commands.md](reference/commands.md).
-- Languages with first-class code support: JavaScript, TypeScript, Vue SFC, and Python.
+- Languages with first-class code support: JavaScript, TypeScript, Vue SFC, Python, Go, Rust, Java, C/C++, Kotlin, Ruby, PHP, C#, Scala, and Swift.
 - `--format json` is the integration surface; tabular output is for humans.

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).

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