@cesarandreslopez/occ 0.12.0 → 0.13.1

package/skills/occ/reference/code.md

@@ -77,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
@@ -103,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
@@ -147,6 +186,19 @@ in-process equivalents for the verbs above, plus a few probes with no CLI:
   / `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);

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

@@ -35,8 +35,11 @@ occ git history src/cli.ts --limit 10
 occ git history --since 2025-01-01 --format json
 ```
 
-Flags: `--limit <n>` (default 50), `--since <date>`, `--follow` (track renames),
-`--line-start <n>` / `--line-end <n>` (for `git log -L` line history).
+Flags: `--limit <n>` (default 50), `--since <date>`, `--scope range|history`
+(default range; `history` logs full HEAD history — the default diff range is
+empty on a clean tree sitting on its base branch), `--follow` (track renames),
+`--line-start <n>` / `--line-end <n>` (for `git log -L` line history). Per-file
+history always logs full HEAD history.
 
 ## `occ git churn`
 
@@ -47,7 +50,8 @@ occ git churn --sort churn --limit 20 --format json
 ```
 
 Flags: `--sort churn|commits|added|deleted|net` (default churn), `--limit <n>`,
-`--since <date>`.
+`--since <date>`, `--scope range|history` (pair `history` with `--since` for a
+windowed hotspot ranking over full HEAD history).
 
 ## `occ git cochange`
 
@@ -60,10 +64,12 @@ 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`,
+Flags: `--limit <n>`, `--since <date>`, `--scope range|history` (pair `history`
+with `--since` for co-change over a real history window), `--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.
+`occ code diff` for symbol-level changed-code context. `--scope history`
+rejects `--base`/`--head`/`--staged` (same rule on history/churn).
 
 ## Symbol-level changes