@cesarandreslopez/occ 0.11.0 → 0.13.0

package/skills/occ/SKILL.md

@@ -9,12 +9,12 @@ description: >-
   "occ sheet inspect", "occ slide inspect", and "occ table inspect"; and code
   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
+  "occ code check", "occ code find", "occ code analyze", "occ code dirtree",
+  "occ code diff", and "occ git diff"/"occ git cochange". 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.11.0
+  version: 0.13.0
 license: MIT
 ---
 
@@ -49,27 +49,30 @@ Run `occ --help` or `occ <group> --help` to see every flag.
 
 ## Decision table — pick the right command
 
-| If you need to…                                         | Start with                                                                     | Deep reference                                   |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
-| Tell what kind of project a directory is                | `occ describe <dir> --format json`                                             | [reference/workspace.md](reference/workspace.md) |
-| Inventory a whole workspace (code + docs + structure)   | `occ workspace analyze <dir> --format json -o ws.json`                         | [reference/workspace.md](reference/workspace.md) |
-| Inventory / cross-reference office docs in a tree       | `occ workspace documents <dir> --format json`                                  | [reference/workspace.md](reference/workspace.md) |
-| Get document + code metrics for some directories        | `occ <dirs> --format json --structure`                                         | [reference/workspace.md](reference/workspace.md) |
-| Preflight one DOCX / PDF / ODT before reading it        | `occ doc inspect <file> --format json`                                         | [reference/documents.md](reference/documents.md) |
-| Preflight an XLSX workbook (schema, sheets, risks)      | `occ sheet inspect <file> --format json`                                       | [reference/documents.md](reference/documents.md) |
-| Preflight a PPTX / ODP deck                             | `occ slide inspect <file> --format json`                                       | [reference/documents.md](reference/documents.md) |
-| Extract structured table data from a document           | `occ table inspect <file> --format json`                                       | [reference/documents.md](reference/documents.md) |
-| Pull entities/keywords (emails, URLs, dates) from a doc | `occ doc entities <file>`                                                      | [reference/documents.md](reference/documents.md) |
-| Get oriented in an unfamiliar codebase                  | `occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md`     | [reference/code.md](reference/code.md)           |
-| 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)           |
-| List changed files / bounded patch / churn              | `occ git changed` · `occ git diff --patch --map-tokens 2048` · `occ git churn` | [reference/git.md](reference/git.md)             |
+| If you need to…                                         | Start with                                                                                          | Deep reference                                   |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Tell what kind of project a directory is                | `occ describe <dir> --format json`                                                                  | [reference/workspace.md](reference/workspace.md) |
+| Inventory a whole workspace (code + docs + structure)   | `occ workspace analyze <dir> --format json -o ws.json`                                              | [reference/workspace.md](reference/workspace.md) |
+| Inventory / cross-reference office docs in a tree       | `occ workspace documents <dir> --format json`                                                       | [reference/workspace.md](reference/workspace.md) |
+| Get document + code metrics for some directories        | `occ <dirs> --format json --structure`                                                              | [reference/workspace.md](reference/workspace.md) |
+| Preflight one DOCX / PDF / ODT before reading it        | `occ doc inspect <file> --format json`                                                              | [reference/documents.md](reference/documents.md) |
+| Preflight an XLSX workbook (schema, sheets, risks)      | `occ sheet inspect <file> --format json`                                                            | [reference/documents.md](reference/documents.md) |
+| Preflight a PPTX / ODP deck                             | `occ slide inspect <file> --format json`                                                            | [reference/documents.md](reference/documents.md) |
+| Extract structured table data from a document           | `occ table inspect <file> --format json`                                                            | [reference/documents.md](reference/documents.md) |
+| Pull entities/keywords (emails, URLs, dates) from a doc | `occ doc entities <file>`                                                                           | [reference/documents.md](reference/documents.md) |
+| Get oriented in an unfamiliar codebase                  | `occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md`                          | [reference/code.md](reference/code.md)           |
+| See an ignore-aware directory tree                      | `occ code dirtree --path . --mode map --format json`                                                | [reference/code.md](reference/code.md)           |
+| 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)           |
+| Hash a symbol body / re-check it later for drift        | `occ code symbol-hash --file <path> --name <name> --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)           |
+| List / re-check cross-module seams (+ co-change)        | `occ code seams --since "90 days ago" --format json` · `occ code seams --resolve <seamKey>`         | [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)           |
+| List changed files / bounded patch / churn / co-change  | `occ git changed` · `occ git diff --patch --map-tokens 2048` · `occ git churn` · `occ git cochange` | [reference/git.md](reference/git.md)             |
 
 ## Recommended agent workflows
 
@@ -79,6 +82,9 @@ Run `occ --help` or `occ <group> --help` to see every flag.
 - **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.
+- **Estimate blast radius:** `occ git cochange --target <path> --format json` for historically coupled files, then use `occ code dirtree --focus-path <dir> --mode map` for structural neighborhood context.
+- **Pin a symbol, detect drift later:** `occ code symbol-hash --file <path> --name <name> --format json`, persist `key` + `bodyHash`, later rerun the same query — a changed hash means the body changed even if the symbol moved lines; `not_found`/`ambiguous` means the key itself drifted.
+- **Map the strongest module relationships:** `occ code seams --since "90 days ago" --format json` ranks cross-module seams by co-change lift; persist `seamKey` and re-check with `occ code seams --resolve <seamKey>` (a `missing` answer is drift, not clean).
 - **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
@@ -86,4 +92,4 @@ Run `occ --help` or `occ <group> --help` to see every flag.
 - 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, Python, Go, Rust, Java, C/C++, Kotlin, Ruby, PHP, C#, Scala, and Swift.
 - `--format json` is the integration surface; tabular output is for humans.
-- Embedding `occ` in a long-running host (an editor/agent integration that holds an index across turns)? The code graph also has an in-process API — fuzzy `searchSymbols`, index-to-context projection, changed-focus repo maps, store freshness probes, and a `health().features` map to feature-detect across versions. See the programmatic surface in [reference/code.md](reference/code.md).
+- Embedding `occ` in a long-running host (an editor/agent integration that holds an index across turns)? The code graph also has an in-process API — fuzzy `searchSymbols`, index-to-context projection, changed-focus repo maps, directory trees, git co-change, store freshness probes, and a `health().features` map to feature-detect across versions. See the programmatic surface in [reference/code.md](reference/code.md).

package/skills/occ/reference/code.md

@@ -31,6 +31,23 @@ occ code map --path . --query "auth token refresh" --focus-path src/auth --map-t
 occ code map --path . --changed-from main --map-tokens 4096   # diff-focused map
 ```
 
+## Directory tree — `occ code dirtree`
+
+Bounded, ignore-aware tree derived from the built code index, not from a raw
+filesystem walk. Use this when you need package/folder shape plus truncation
+breadcrumbs for drill-in.
+
+```bash
+occ code dirtree --path . --format json
+occ code dirtree --path . --mode map --map-tokens 4096 --tokenizer o200k_base
+occ code dirtree --path . --focus-path src/code --depth 4 --max-entries 25
+```
+
+Modes: `compact` (default, collapses single-child directory chains), `verbose`,
+and `map` (compact plus top symbol signatures from the highest-ranked file per
+directory). JSON output includes `truncatedPaths`; call again with
+`--focus-path <path>` and higher caps to drill into an elided subtree.
+
 ## Search — `occ code find <mode>`
 
 - `occ code find fused "<query>"` — combines name + pattern + content search with
@@ -60,6 +77,25 @@ 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.
 
+## Symbol drift — `occ code symbol-hash`
+
+Hash symbol bodies by a stable, line-independent key
+(`{relativePath, name, kind?, containerName?}`). Node ids embed the line, so
+they churn on any edit above the symbol; symbol keys do not. Persist the
+returned `bodyHash` (frozen contract: full 64-hex sha256 of the exact source
+span) and rerun the same query later — a different hash means the body changed.
+
+```bash
+occ code symbol-hash --path . --file src/main.ts --name bootstrap --format json
+occ code symbol-hash --path . --queries-json queries.json --format json   # batch; - reads stdin
+```
+
+Per-query statuses: `resolved` / `not_found` / `ambiguous` (with candidates —
+add `--kind` or `--container` to disambiguate) / `error`. Batch entries are
+independent; results align positionally with the queries. Any non-resolved
+result exits nonzero. `spanExact: false` means the parser only gave a
+declaration line (regex-fallback languages) — fall back to file-level hashing.
+
 ## Syntax checks — `occ code check`
 
 Use `check` as a lightweight post-edit parse gate before wider tests. It supports
@@ -86,6 +122,26 @@ occ code check src/App.vue --format json
 `calls`/`callers`/`tree` accept `--file <path>` to disambiguate. Relationships
 report `resolved` / `ambiguous` / `unresolved` status explicitly.
 
+## Seams — `occ code seams`
+
+Enumerate cross-module seams: import/call edges between directory-modules,
+optionally weighted by git co-change. Use it to find the strongest ungoverned
+relationships in a repo and to durably reference one.
+
+```bash
+occ code seams --path . --since "90 days ago" --limit 20 --format json
+occ code seams --path . --resolve "seam:src::src/code" --format json
+```
+
+Each seam carries `seamKey` (`seam:` + both modules sorted, `::`-joined),
+`importEdgeCount`, `callEdgeCount`, optional `cochange {count, lift,
+lastCochangedAt}`, and `rank`. `--since` aggregates co-change over full HEAD
+history bounded by the window and works with `--path` below the git toplevel.
+`--min-lift <n>` filters by lift (needs `--since`); `--resolve` answers
+`resolved`/`missing` per key and exits nonzero when anything is missing. A
+directory rename changes the key by design — treat `missing` as drift, never
+as clean.
+
 ## Change-aware — `occ code diff` / `occ code history`
 
 ```bash
@@ -126,6 +182,23 @@ in-process equivalents for the verbs above, plus a few probes with no CLI:
   admitted entries carry `changed`/`churn`. `toRepoMapChangeContext` /
   `stampRepoMapChanges` are exported for callers that already hold a diff
   summary. Facade: `createOcc().code.mapChanged`.
+- **`buildDirectoryTree(index, options)`** / `session.getDirectoryTree(options)`
+  / `createOcc().code.directoryTree(index, options)` — bounded directory tree
+  over indexed files, with `compact`/`verbose`/`map` modes and
+  `truncatedPaths` drill-in hints.
+- **`hashCodeSymbols(index, queries, options?)`** / `session.hashSymbols(...)`
+  — the batch body-hash primitive behind `occ code symbol-hash`. Facade:
+  `createOcc().code.symbolHash`. Gate on
+  `health.features?.['code.symbol.bodyHash'] === true`.
+- **`listCodeSeams(index, { cochange?, minLift?, limit? })`** /
+  `resolveCodeSeams(index, seamKeys, options?)` / `session.seams(...)` /
+  `session.resolveSeams(...)` — seam enumeration and freshness checks. Pure:
+  pass a `GitCochangeSummary` from `getGitCochange` to attach co-change (use
+  `scope: 'history'` with `since` for a windowed history join, and
+  `rebaseCochangeToIndexRoot(summary, prefix)` when the index root sits below
+  the git toplevel — git paths are toplevel-relative). Facade:
+  `createOcc().code.seams` / `.resolveSeams`; `seamKeyFor(moduleA, moduleB)` is
+  exported for key construction. Gate on `health.features?.['code.seams']`.
 - **`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);
@@ -134,7 +207,7 @@ in-process equivalents for the verbs above, plus a few probes with no CLI:
   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
+  `code.searchSymbols`, `code.directoryTree`, `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.
 

package/skills/occ/reference/commands.md

@@ -39,7 +39,9 @@ tabular|json`, `-o <file>`, and `--ci`.
 - `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 symbol-hash` — Hash symbol bodies by stable line-independent key (sha256 of the exact source span).
 - `occ code check <file>` — Check a file's syntax without a language server (exits nonzero only when invalid).
+- `occ code dirtree` — Render a bounded directory tree from the built code index.
 - `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.
@@ -51,6 +53,7 @@ tabular|json`, `-o <file>`, and `--ci`.
 - `occ code analyze deps <target>` — Show module/file import relationships.
 - `occ code analyze coupling <target>` — Show module-level coupling metrics.
 - `occ code analyze tree <className>` — Show class/interface inheritance relationships.
+- `occ code seams` — Enumerate cross-module seams (`--since` joins co-change, `--resolve` re-checks keys).
 - `occ code diff` — Show changed symbols for a git diff range.
 - `occ code history <symbol>` — Show git line history for a symbol.
 
@@ -60,6 +63,7 @@ tabular|json`, `-o <file>`, and `--ci`.
 - `occ git diff` — Summarize or render the resolved diff (`--patch` for a bounded raw patch).
 - `occ git history [file]` — Show commit history for a range or file.
 - `occ git churn` — Rank changed files by churn.
+- `occ git cochange` — Rank file pairs that historically change together (count + lift).
 
 ## `occ skills` — Install and inspect the Agent Skills bundled with occ
 

package/skills/occ/reference/git.md

@@ -1,6 +1,6 @@
 # Git context
 
-Inspect git changes, history, and churn. Shared flags: `--path <repo-root>`
+Inspect git changes, history, churn, and file-level co-change. Shared flags: `--path <repo-root>`
 (default cwd), `--base <ref>`, `--head <ref>`, `--staged`, `--format
 tabular|json`, `-o <file>`. The diff range is resolved from `--base`/`--head`/
 `--staged` (defaults to the working-tree changes when unspecified).
@@ -49,6 +49,22 @@ occ git churn --sort churn --limit 20 --format json
 Flags: `--sort churn|commits|added|deleted|net` (default churn), `--limit <n>`,
 `--since <date>`.
 
+## `occ git cochange`
+
+Rank file pairs that historically change together. Use this for file-level
+blast-radius hints before editing a known path.
+
+```bash
+occ git cochange --limit 20 --format json
+occ git cochange --target src/cli.ts --format json
+occ git cochange --since 2025-01-01 --max-commit-files 30
+```
+
+Flags: `--limit <n>`, `--since <date>`, `--target <path>`, and
+`--max-commit-files <n>` (default 50). JSON pairs include `fileA`, `fileB`,
+`count`, `lift`, and `lastCochangedAt`. Co-change is file-level only; use
+`occ code diff` for symbol-level changed-code context.
+
 ## Symbol-level changes
 
 To see which _symbols_ (not just files/lines) changed, use `occ code diff`