From 7ccfa05bd5c07648321875556af5b27bc70ce634 Mon Sep 17 00:00:00 2001 From: copyleftdev Date: Thu, 9 Apr 2026 18:08:03 -0700 Subject: [PATCH] docs: document all new features from 10 merged PRs Add documentation for cascade command, stats --window/--time-field flags, drift --group-by flag, git/cpuprofile/strace input formats, health profile, vajra-domain-github plugin, --semantic-paths flag, and NDJSON aggregation behavior change. Updates mdBook docs, SUMMARY.md, and man page. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/src/SUMMARY.md | 1 + docs/src/cmd-cascade.md | 142 ++++++++++++++++++++++++++++++++++++++++ docs/src/cmd-drift.md | 32 +++++++++ docs/src/cmd-stats.md | 37 +++++++++++ docs/src/formats.md | 88 +++++++++++++++++++++++-- docs/src/plugins.md | 41 +++++++++++- docs/src/profiles.md | 41 ++++++++++++ man/vajra.1 | 79 ++++++++++++++++++++-- 8 files changed, 444 insertions(+), 17 deletions(-) create mode 100644 docs/src/cmd-cascade.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 5ea1b7d..b413255 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -17,6 +17,7 @@ - [invariants](./cmd-invariants.md) - [query](./cmd-query.md) - [batch](./cmd-batch.md) + - [cascade](./cmd-cascade.md) - [Profiles](./profiles.md) - [Input Formats](./formats.md) - [The Engine](./engine.md) diff --git a/docs/src/cmd-cascade.md b/docs/src/cmd-cascade.md new file mode 100644 index 0000000..c62de39 --- /dev/null +++ b/docs/src/cmd-cascade.md @@ -0,0 +1,142 @@ +# cascade + +`cascade` detects temporal cause-effect chains in event data. Given a stream of timestamped events grouped by entity, it identifies sequences where one event type triggers another — and measures how reliably that pattern holds. + +Where `anomalies` finds single-record outliers, `cascade` finds multi-record temporal patterns: event A happens to entity X, then event B follows within a window. + +--- + +## Usage + +```bash +vajra cascade [flags] +``` + +**Arguments:** + +| Argument | Description | +|---|---| +| `` | Path to a JSON/NDJSON file, `-` for stdin, or an HTTP URL | + +**Flags:** + +| Flag | Description | Default | +|---|---|---| +| `--entity-field ` | JSONPath to the entity identifier (e.g., `'$.author'`) | required | +| `--time-field ` | JSONPath to the timestamp field (e.g., `'$.date'`) | required | +| `--event-field ` | JSONPath to the event type field (e.g., `'$.type'`) | required | +| `--response-values ` | Comma-separated list of event values that count as responses (e.g., `fix,revert`) | required | +| `--format ` | Output format: `text`, `json`, `markdown`, `compact-ai` | `text` | +| `--input-format ` | Override auto-detected input format | auto | +| `--quiet` | Suppress progress output | off | + +--- + +## What It Reports + +### Cascade Rate + +The fraction of trigger events that are followed by a response event from the same entity within the detection window. A high cascade rate means the cause-effect pattern is reliable. + +### Self-Fix Rate + +The fraction of cascades where the same entity that caused the trigger also produced the response. Measures whether entities clean up their own problems. + +### Hot Entities + +Entities that appear disproportionately in cascade chains. These are the nexus points — the authors, services, or components that most frequently participate in cause-and-effect sequences. + +### Cascade Chains + +The full chain detail: trigger event, response event, entity, timestamps, and time delta between cause and effect. + +--- + +## Algorithm + +O(n log n). Records are grouped by entity using a BTreeMap (ordered map), sorted by timestamp within each group, then scanned linearly to detect trigger-response pairs. The BTreeMap ensures deterministic iteration order regardless of input ordering. + +--- + +## Example: Commit Cascade Analysis + +```bash +vajra cascade commits.ndjson \ + --entity-field '$.author' \ + --time-field '$.date' \ + --event-field '$.type' \ + --response-values 'fix,revert' +``` + +```text +=== Cascade Report === +Records: 1,247 +Entities: 34 +Trigger events: 312 +Response events: 89 + +Cascade rate: 0.285 (89 of 312 triggers followed by a response) +Self-fix rate: 0.742 (66 of 89 responses by the same entity) + +Hot entities: + alice 23 cascades (25.8%) + bob 14 cascades (15.7%) + charlie 9 cascades (10.1%) + +Cascade chains (top 5 by frequency): + bug -> fix 62 occurrences, median delta: 2.3 days + bug -> revert 18 occurrences, median delta: 0.4 days + regression -> fix 9 occurrences, median delta: 4.1 days +``` + +--- + +## Example: JSON Output + +```bash +vajra cascade commits.ndjson \ + --entity-field '$.author' \ + --time-field '$.date' \ + --event-field '$.type' \ + --response-values 'fix,revert' \ + --format json +``` + +```json +{ + "records": 1247, + "entities": 34, + "trigger_events": 312, + "response_events": 89, + "cascade_rate": 0.285, + "self_fix_rate": 0.742, + "hot_entities": [ + {"entity": "alice", "cascades": 23, "fraction": 0.258}, + {"entity": "bob", "cascades": 14, "fraction": 0.157}, + {"entity": "charlie", "cascades": 9, "fraction": 0.101} + ], + "chains": [ + {"trigger": "bug", "response": "fix", "count": 62, "median_delta_days": 2.3}, + {"trigger": "bug", "response": "revert", "count": 18, "median_delta_days": 0.4}, + {"trigger": "regression", "response": "fix", "count": 9, "median_delta_days": 4.1} + ] +} +``` + +--- + +## When to Use It + +- **Incident response analysis.** Which errors lead to fixes, and how quickly? Which lead to reverts? +- **Developer workflow.** Who introduces bugs and who fixes them? Is there a self-fix pattern? +- **Service dependency.** Event A in service X triggers event B in service Y — cascade reveals the coupling. +- **Repository health.** Measure how reliably bugs get resolved and how long the resolution takes. + +--- + +## Pairs Well With + +- [`stats`](./cmd-stats.md) — statistical profile of the event fields before cascade analysis +- [`anomalies`](./cmd-anomalies.md) — unusual cascade chains (an entity that never self-fixes) are anomaly candidates +- [`invariants`](./cmd-invariants.md) — cascade patterns are temporal invariants; invariants discovers structural ones +- [`essence`](./cmd-essence.md) — cascade metrics feed into essence generation for project health assessments diff --git a/docs/src/cmd-drift.md b/docs/src/cmd-drift.md index 1e7cf40..cfa5142 100644 --- a/docs/src/cmd-drift.md +++ b/docs/src/cmd-drift.md @@ -28,6 +28,38 @@ vajra drift [flags] | `--input-format ` | Override auto-detected input format | auto | | `--redact` | Apply built-in redaction before output | off | | `--quiet` | Suppress progress output | off | +| `--group-by ` | JSONPath for population-level comparison (e.g., `'$.author_type'`) | off | + +--- + +## Population-Level Comparison + +When `--group-by` is specified, `drift` partitions records by the field value and computes pairwise drift between all groups. Instead of comparing two documents, you compare two (or more) subpopulations within the same dataset. + +```bash +vajra drift prs.ndjson --group-by '$.author_type' +``` + +```text +Drift Report (grouped by $.author_type) +Groups: bot (412 records), human (835 records) + +Pairwise drift: bot vs human + Structural similarity: 0.91 (Jaccard) + + Distribution shifts: + $.files_changed JSD: 0.42 (high) + bot: median 1.0, p95 3.0 + human: median 4.0, p95 18.0 + + $.review_comments JSD: 0.38 (moderate) + bot: median 0.0, p95 1.0 + human: median 2.0, p95 8.0 + + Overall severity: HIGH (significant distributional divergence) +``` + +This is useful for comparing behavioral subgroups — bot vs. human PRs, different teams, production vs. staging, before vs. after a policy change — without needing separate files. --- diff --git a/docs/src/cmd-stats.md b/docs/src/cmd-stats.md index f307590..828b586 100644 --- a/docs/src/cmd-stats.md +++ b/docs/src/cmd-stats.md @@ -27,6 +27,43 @@ vajra stats [flags] | `--streaming` | Force streaming mode (sketch-based approximations) | off | | `--redact` | Apply built-in redaction before output | off | | `--quiet` | Suppress progress output | off | +| `--window ` | Temporal windowing: `month`, `week`, or `day` | off | +| `--time-field ` | JSONPath to timestamp field (e.g., `'$.date'`). Auto-detected if omitted. | auto | + +--- + +## Temporal Windowing + +When `--window` is specified, `stats` partitions records by time period and computes per-window statistics. Cross-window trend lines are included in the output, showing how distributions shift over time. + +The `--time-field` flag tells Vajra which field contains the timestamp. If omitted, Vajra auto-detects by scanning for fields with date/time patterns (ISO 8601, Unix timestamps, common date formats). + +```bash +vajra stats commits.ndjson --window month --time-field '$.date' +``` + +```text +=== Statistical Summary (windowed: month) === +Document: commits.ndjson (1,247 records, 8 paths) + +--- Window: 2026-01 (312 records) --- + $.files_changed + Mean: 4.2 Median: 3.0 p95: 12.0 + +--- Window: 2026-02 (298 records) --- + $.files_changed + Mean: 5.1 Median: 4.0 p95: 15.0 + +--- Window: 2026-03 (337 records) --- + $.files_changed + Mean: 6.8 Median: 5.0 p95: 19.0 + +--- Cross-Window Trends --- + $.files_changed mean: 4.2 -> 5.1 -> 6.8 (upward, +62% over 3 months) + $.type "fix" share: 0.18 -> 0.24 -> 0.31 (increasing) +``` + +Windowing works with any multi-record input: NDJSON, CSV, multi-document YAML, or directories. --- diff --git a/docs/src/formats.md b/docs/src/formats.md index 05783e6..41614bb 100644 --- a/docs/src/formats.md +++ b/docs/src/formats.md @@ -19,6 +19,9 @@ Vajra reads more than JSON. It reads anything that can be interpreted as structu | Zstd | `.zst`, `.json.zst` | Zstd magic bytes | Decompressed transparently. Inner format auto-detected. | | HTTP URL | `http://`, `https://` | URL scheme prefix | Fetched via blocking HTTP GET. Response body auto-detected. | | Source Code | `.rs`, `.py`, `.js`, `.ts`, `.go`, `.java`, `.c`, `.cpp`, `.rb` | File extension matches known language | Parsed via tree-sitter into AST. Requires `vajra-source` feature. | +| Git Repository | (directory) | Directory contains `.git/` | Reads commit history directly. See flags below. | +| V8 CPU Profile | `.cpuprofile` | File extension | Parses V8 `.cpuprofile` JSON into analyzable structure. | +| strace Summary | — | Content contains `% time` header | Parses `strace -c` summary output into structured records. | | Stdin | `-` | Explicit `-` argument | Content auto-detected from first bytes. | --- @@ -27,9 +30,9 @@ Vajra reads more than JSON. It reads anything that can be interpreted as structu When no `--input-format` is specified, Vajra detects the format in this order: -1. **Check the argument.** If it is `-`, read from stdin. If it starts with `http://` or `https://`, fetch via HTTP. +1. **Check the argument.** If it is `-`, read from stdin. If it starts with `http://` or `https://`, fetch via HTTP. If it is a directory containing `.git/`, treat as a git repository. -2. **Check the extension.** `.json` -> JSON. `.ndjson`/`.jsonl` -> NDJSON. `.yaml`/`.yml` -> YAML. `.csv` -> CSV. `.tsv` -> TSV. `.md` -> Markdown. `.pdf` -> PDF. `.rs`/`.py`/`.js`/`.go`/etc. -> Source Code (via tree-sitter). +2. **Check the extension.** `.json` -> JSON. `.ndjson`/`.jsonl` -> NDJSON. `.yaml`/`.yml` -> YAML. `.csv` -> CSV. `.tsv` -> TSV. `.md` -> Markdown. `.pdf` -> PDF. `.cpuprofile` -> V8 CPU Profile. `.rs`/`.py`/`.js`/`.go`/etc. -> Source Code (via tree-sitter). 3. **Check for compression.** If the extension is `.gz` or `.zst`, decompress and re-detect the inner format from the next extension (e.g., `.json.gz` -> decompress -> JSON). @@ -39,6 +42,7 @@ When no `--input-format` is specified, Vajra detects the format in this order: - Starts with `---` or matches `key: value` pattern -> YAML - Consistent comma-separated columns -> CSV - PDF magic bytes (`%PDF`) -> PDF + - Contains `% time` column header -> strace summary 5. **Fall back to JSON.** If nothing else matches, attempt JSON parsing. @@ -80,7 +84,7 @@ Each line is an independent JSON document. Natural format for logs, event stream vajra anomalies claims.ndjson ``` -Every line becomes a separate document in the analysis. Commands like `anomalies` and `invariants` treat the lines as a population. +NDJSON records are aggregated into a single array for analysis. Commands like `stats`, `anomalies`, `invariants`, and `essence` compute across all records as a unified population. Example input: @@ -214,6 +218,78 @@ vajra inspect code.txt --input-format source --lang python # override format + Source code analysis requires the `vajra-source` crate (included by default). The companion `vajra-domain-source` plugin adds recognizers for naming conventions (snake_case, camelCase, PascalCase) and code structure relationships. +#### Semantic Paths + +The `--semantic-paths` flag maps tree-sitter node kinds to human-readable labels in the output. Instead of raw AST node names like `function_item` or `impl_item`, you see `function` and `implementation`. + +```bash +vajra inspect main.rs --semantic-paths +``` + +Without `--semantic-paths`: + +```text +$.program.function_item[0].identifier "process_record" +$.program.function_item[0].parameters.parameter[0] "record: &Record" +$.program.impl_item[0].identifier "Pipeline" +``` + +With `--semantic-paths`: + +```text +$.program.function[0].name "process_record" +$.program.function[0].parameters.param[0] "record: &Record" +$.program.implementation[0].name "Pipeline" +``` + +Covers 9 languages: Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, and Ruby. + +### Git Repository + +When the input is a directory containing a `.git/` subdirectory, Vajra reads the commit history directly — no export step required. + +```bash +vajra stats ./my-repo +vajra cascade ./my-repo --entity-field '$.author' --time-field '$.date' --event-field '$.type' --response-values 'fix,revert' +``` + +Each commit becomes a JSON record with fields like `author`, `date`, `message`, `files_changed`, and `insertions`/`deletions`. + +**Flags:** + +| Flag | Description | Default | +|---|---|---| +| `--git-limit ` | Maximum number of commits to read | 500 | +| `--git-branch ` | Branch to read from | current HEAD | + +```bash +vajra stats ./my-repo --git-limit 1000 --git-branch main +``` + +Auto-detection is based on the presence of `.git/` in the input directory. To override, use `--input-format git`. + +### V8 CPU Profile + +Vajra parses `.cpuprofile` files produced by V8-based tools (Chrome DevTools, Node.js `--prof`). The profile's call tree is converted to a flat array of records with function name, source location, hit count, and self/total time. + +```bash +vajra stats profile.cpuprofile +vajra anomalies profile.cpuprofile +``` + +Auto-detected by the `.cpuprofile` extension. + +### strace Summary + +Vajra parses the summary table produced by `strace -c`. Each syscall row becomes a record with fields for time percentage, seconds, calls, errors, and syscall name. + +```bash +strace -c ls 2>&1 | vajra stats - +vajra stats strace_output.txt --input-format strace +``` + +Auto-detected when content contains the `% time` column header characteristic of `strace -c` output. + --- ### Compressed Files (Gzip, Zstd) @@ -257,13 +333,11 @@ zcat claims.json.gz | vajra inspect - ## Multi-Document Formats -NDJSON and multi-document YAML naturally contain multiple documents. When fed to single-document commands (`inspect`, `stats`, `fingerprint`), Vajra analyzes the first document. When fed to multi-document commands (`anomalies`, `invariants`, `batch`), all documents are analyzed as a population. - -To explicitly analyze all documents from a multi-document format: +NDJSON and multi-document YAML naturally contain multiple documents. NDJSON records are now aggregated into a single array, so all commands — including `stats`, `anomalies`, `invariants`, and `essence` — compute across all records as a unified population. ```bash vajra anomalies claims.ndjson # analyzes all lines as a batch -vajra stats claims.ndjson # analyzes the first line only +vajra stats claims.ndjson # computes stats across all records ``` --- diff --git a/docs/src/plugins.md b/docs/src/plugins.md index 97c1691..dc3eb45 100644 --- a/docs/src/plugins.md +++ b/docs/src/plugins.md @@ -267,7 +267,7 @@ A plugin **may not:** ## Shipped Plugins -Five domain plugins ship with Vajra, all enabled by default via feature flags: +Six domain plugins ship with Vajra, all enabled by default via feature flags: | Domain | Plugin | Type Recognizers | Hints | |---|---|---|---| @@ -276,19 +276,21 @@ Five domain plugins ship with Vajra, all enabled by default via feature flags: | DevOps | `vajra-domain-devops` | Container ID, Semver, Git SHA, Docker Image, AWS ARN, GCP Resource, CIDR, Cron, K8s Namespace, Terraform Resource | 6 (K8s pod spec, deployment metadata, service endpoint, Terraform, CI pipeline, container spec) | | Source Code | `vajra-domain-source` | snake_case, camelCase, PascalCase, SCREAMING_SNAKE, import paths, source file paths | 6 (function definition, class definition, import statement, parameter list, conditional, loop) | | Encoding | `vajra-domain-encoding` | Base64, Base64URL, hex, URL-encoded, HTML entities, Unicode escapes, PEM, data URI, quoted-printable, MIME encoded word, Punycode, double-encoded, mixed-encoding | 3 (content+encoding, transfer encoding, encoded/decoded pairs) | +| GitHub | `vajra-domain-github` | PR number, issue number, GitHub username, repo slug, commit SHA, branch name, label, milestone, review state, merge method | 7 (pull request, issue, review, commit, release, workflow run, discussion) | ### Feature Flags ```toml # vajra-cli/Cargo.toml [features] -default = ["medical", "security", "devops", "source", "encoding"] +default = ["medical", "security", "devops", "source", "encoding", "github"] medical = ["vajra-domain-med"] security = ["vajra-domain-sec"] devops = ["vajra-domain-devops"] source = ["vajra-source", "vajra-domain-source"] encoding = ["vajra-domain-encoding"] -all-plugins = ["medical", "security", "devops", "source", "encoding"] +github = ["vajra-domain-github"] +all-plugins = ["medical", "security", "devops", "source", "encoding", "github"] ``` Build without a plugin: `cargo build --no-default-features --features security,devops` @@ -416,6 +418,39 @@ Bounded at depth 5, decode capped at 4KB per layer. Catches `base64(url(hex(payl --- +## The GitHub Plugin: vajra-domain-github + +The GitHub plugin recognizes types commonly found in GitHub API responses, webhook payloads, and exported repository data (PRs, issues, commits, reviews, releases, workflow runs). + +### Type Recognizers + +| Recognized Type | Pattern | Priority | Confidence | Example Values | +|---|---|---|---|---| +| PR Number | `#\d+` or bare integer in PR context | 10 | 0.90 | `#142`, `1587` | +| Issue Number | `#\d+` or bare integer in issue context | 10 | 0.90 | `#23`, `456` | +| GitHub Username | `[a-zA-Z0-9](-?[a-zA-Z0-9]){0,38}` | 20 | 0.75 | `copyleftdev`, `octocat` | +| Repo Slug | `owner/repo` pattern | 15 | 0.85 | `copyleftdev/vajra`, `rust-lang/rust` | +| Commit SHA | 7-40 hex chars in commit context | 10 | 0.95 | `a1b2c3d`, full 40-char SHA | +| Branch Name | Ref-like strings with `/` separators | 25 | 0.70 | `main`, `feature/cascade-cmd` | +| Label | Known label patterns (bug, enhancement, etc.) | 30 | 0.65 | `bug`, `good first issue` | +| Milestone | Version-like or sprint-like strings | 30 | 0.60 | `v1.0`, `Sprint 12` | +| Review State | One of: approved, changes_requested, commented, dismissed | 5 | 1.00 | `approved`, `changes_requested` | +| Merge Method | One of: merge, squash, rebase | 5 | 1.00 | `squash`, `rebase` | + +### Relationship Hints + +| Hint | Field Patterns | Meaning | +|---|---|---| +| Pull Request | `number`, `title`, `state`, `author`, `base`, `head` | A pull request record | +| Issue | `number`, `title`, `state`, `labels`, `assignees` | An issue record | +| Review | `author`, `state`, `body`, `submitted_at` | A PR review | +| Commit | `sha`, `message`, `author`, `date` | A commit record | +| Release | `tag_name`, `name`, `published_at`, `assets` | A release record | +| Workflow Run | `name`, `status`, `conclusion`, `run_number` | A CI workflow run | +| Discussion | `title`, `author`, `category`, `answer` | A GitHub discussion | + +--- + ## Future Plugin Domains The architecture supports any domain: diff --git a/docs/src/profiles.md b/docs/src/profiles.md index 4c3cc50..518254f 100644 --- a/docs/src/profiles.md +++ b/docs/src/profiles.md @@ -211,6 +211,46 @@ Flagged Patterns: --- +### health + +**For:** Project and repository health assessment. Identifies risks, governance patterns, and sustainability signals. + +| Dimension | Weight | +|---|---| +| entropy_signal | 0.25 | +| concern_relevance | 0.25 | +| anomaly_strength | 0.20 | +| rarity | 0.15 | +| instability | 0.10 | +| structural_coverage | 0.05 | + +**Rendering:** Assessment-oriented. Sections organized around risk, governance, and sustainability. Designed for repository and project analysis. + +**Section headers:** "Key Risks," "Governance Signals," "Sustainability Assessment." + +```bash +vajra essence ./my-repo --profile health +``` + +```text +Key Risks: + - Bus factor: 2 contributors account for 78% of commits. + - Fix rate declining: 31% of bugs fixed in March vs 18% in January. + - Mean time to fix increasing: 2.3 days -> 4.1 days over 3 months. + +Governance Signals: + - Review coverage: 64% of PRs received at least one review. + - Bot contribution: 33% of PRs from automated tools. + - Consistent commit cadence: 4.2 commits/day (low variance). + +Sustainability Assessment: + - Moderate risk. High contributor concentration and declining fix rates + suggest capacity constraints. Review coverage is below recommended + thresholds for projects of this activity level. +``` + +--- + ## Custom Profiles Define custom profiles in TOML. Load with `--config path/to/profiles.toml`. @@ -281,6 +321,7 @@ vajra profiles auditor Formal vocabulary, completeness-focused; emphasizes instability and concern relevance ai Compact terse rendering optimized for machine consumption fraud Investigative framing; emphasizes outliers, rarity, and suspicious patterns + health Assessment-oriented; emphasizes risks, governance, and sustainability === Custom Profiles === claims-review Internal claims processing review diff --git a/man/vajra.1 b/man/vajra.1 index 60e77e8..f15a74e 100644 --- a/man/vajra.1 +++ b/man/vajra.1 @@ -10,10 +10,11 @@ vajra \- deterministic semantic reduction engine for structured data [\fIARGS\fR] .SH DESCRIPTION .B Vajra -analyzes arbitrary structured data \(em JSON, YAML, CSV, NDJSON, Markdown, and PDF -\(em extracts structural fingerprints, computes entropy and statistical profiles, -detects anomalies and schema drift, discovers cross-field relationships, and -renders deterministic essences optimized for humans, auditors, and AI pipelines. +analyzes arbitrary structured data \(em JSON, YAML, CSV, NDJSON, Markdown, PDF, +git repositories, V8 CPU profiles, and strace output \(em extracts structural +fingerprints, computes entropy and statistical profiles, detects anomalies and +schema drift, discovers cross-field relationships, detects temporal cascades, +and renders deterministic essences optimized for humans, auditors, and AI pipelines. .PP Every analysis is deterministic: the same input with the same configuration always produces byte-identical output. @@ -23,10 +24,12 @@ always produces byte-identical output. Full structural analysis. Shows document metadata, all wildcard paths with types and counts, BLAKE3 fingerprints, and domain type recognition. .TP -.B stats \fIINPUT\fR +.B stats \fIINPUT\fR [\fB\-\-window\fR \fIPERIOD\fR] [\fB\-\-time\-field\fR \fIPATH\fR] Statistical summary. Per-path Shannon entropy, cardinality, frequency distributions, numeric statistics (min, max, median, MAD, percentiles), -and top values. +and top values. With \fB\-\-window\fR (month|week|day), partitions records +by time period and includes cross-window trend lines. \fB\-\-time\-field\fR +specifies the timestamp field; auto-detected if omitted. .TP .B anomalies \fIINPUT\fR Anomaly detection. MAD-based numeric outliers, rarity scoring via @@ -41,10 +44,12 @@ Generate a concern-oriented essence. Scores observations using the active profile's weight vector, ranks by importance, and renders in the requested format. Supports token budgets for LLM context window optimization. .TP -.B drift \fIBASELINE\fR \fICANDIDATE\fR +.B drift \fIBASELINE\fR \fICANDIDATE\fR [\fB\-\-group\-by\fR \fIPATH\fR] Schema drift detection between two documents. Reports added/removed paths, type changes, and distributional shifts measured by Jensen-Shannon Divergence and 1D Wasserstein distance. Classifies severity as None/Low/Medium/High/Critical. +With \fB\-\-group\-by\fR, partitions records by field value and computes pairwise +drift between all groups within a single dataset. .TP .B cluster \fIINPUTS...\fR Cluster similar documents by structural similarity. Uses MinHash signatures @@ -65,6 +70,12 @@ Parallel batch analysis of all JSON files in a directory using Rayon. Reports per-document summaries and aggregate statistics including common and rare paths. .TP +.B cascade \fIINPUT\fR [\fB\-\-entity\-field\fR \fIPATH\fR] [\fB\-\-time\-field\fR \fIPATH\fR] [\fB\-\-event\-field\fR \fIPATH\fR] [\fB\-\-response\-values\fR \fIVALS\fR] +Temporal cause-effect chain detection. Groups events by entity, sorts by +timestamp, and identifies trigger-response patterns. Reports cascade rate, +self-fix rate, hot entities, and full cascade chains. Algorithm: O(n log n) +BTreeMap grouping + sort + linear scan. +.TP .B profiles List all available profiles (built-in and custom from \fB\-\-config\fR). .SH GLOBAL OPTIONS @@ -105,6 +116,16 @@ Suppress progress output. .TP .B \-\-explain Include score decomposition in essence output. +.TP +.B \-\-semantic\-paths +Map tree-sitter AST node kinds to human-readable labels in source code output. +Covers 9 languages (Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, Ruby). +.TP +.BI \-\-git\-limit " N" +Maximum number of commits to read when input is a git repository. Default: 500. +.TP +.BI \-\-git\-branch " BRANCH" +Branch to read when input is a git repository. Default: current HEAD. .SH INPUT FORMATS .B Vajra auto-detects input format from file extension and content: @@ -119,14 +140,21 @@ auto-detects input format from file extension and content: \&.tsv Tab-separated values \&.md, .markdown Markdown \&.pdf PDF (text extraction) +\&.cpuprofile V8 CPU profile \&.gz Gzip compressed (any format) \&.zst, .zstd Zstd compressed (any format) http://, https:// HTTP URL (fetched automatically) \- Standard input +(directory)/.git Git repository (reads commit history) +(content) strace -c summary (auto-detected by "% time" header) .fi .RE .PP Double extensions are supported: \fB.json.gz\fR decompresses then parses as JSON. +.PP +NDJSON records are aggregated into a single array for analysis. Commands like +\fBstats\fR, \fBanomalies\fR, \fBinvariants\fR, and \fBessence\fR compute across +all records as a unified population. .SH PROFILES .SS staff Weights: anomaly_strength=0.30, structural_coverage=0.25, concern_relevance=0.20. @@ -144,6 +172,11 @@ Terse machine-parseable output. In compact-ai format, uses short keys .SS fraud Weights: anomaly_strength=0.35, rarity=0.25. Investigative framing with RISK/ALERT labels for outliers and suspicious patterns. +.SS health +Weights: entropy_signal=0.25, concern_relevance=0.25, anomaly_strength=0.20, +rarity=0.15, instability=0.10, structural_coverage=0.05. +Assessment-oriented rendering with sections for Key Risks, Governance Signals, +and Sustainability Assessment. Designed for repository and project health analysis. .SH ALGORITHMS All algorithms satisfy three gates: O(n) or O(n log n) time complexity, published and peer-reviewed, and fully deterministic. @@ -226,6 +259,38 @@ Pipe from stdin with redaction: curl -s https://api.example.com/patient | vajra essence - --profile staff --redact .fi .RE +.PP +Detect temporal cascades in commit data: +.PP +.RS +.nf +vajra cascade commits.ndjson --entity-field '$.author' --time-field '$.date' --event-field '$.type' --response-values 'fix,revert' +.fi +.RE +.PP +Analyze a git repository directly: +.PP +.RS +.nf +vajra stats ./my-repo --window month +.fi +.RE +.PP +Assess project health: +.PP +.RS +.nf +vajra essence ./my-repo --profile health +.fi +.RE +.PP +Compare subpopulations with group-by drift: +.PP +.RS +.nf +vajra drift prs.ndjson --group-by '$.author_type' +.fi +.RE .SH FILES .TP .B ~/.vajra/config.toml