{"id":51858306,"url":"https://github.com/anky2901/repo-xray","last_synced_at":"2026-07-24T03:01:04.070Z","repository":{"id":370951840,"uuid":"1298031157","full_name":"anky2901/repo-xray","owner":"anky2901","description":"Local-first repository intelligence — security, architecture, dependencies, tests, CI, release readiness, and more, with explainable findings.","archived":false,"fork":false,"pushed_at":"2026-07-12T06:39:41.000Z","size":196,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-12T08:11:52.850Z","etag":null,"topics":["cli","code-quality","developer-tools","monorepo","sarif","security","static-analysis","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anky2901.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-12T06:12:27.000Z","updated_at":"2026-07-12T06:39:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anky2901/repo-xray","commit_stats":null,"previous_names":["anky2901/repo-xray"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/anky2901/repo-xray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anky2901%2Frepo-xray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anky2901%2Frepo-xray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anky2901%2Frepo-xray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anky2901%2Frepo-xray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anky2901","download_url":"https://codeload.github.com/anky2901/repo-xray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anky2901%2Frepo-xray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35824609,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-24T02:00:07.870Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","code-quality","developer-tools","monorepo","sarif","security","static-analysis","typescript"],"created_at":"2026-07-24T03:01:00.397Z","updated_at":"2026-07-24T03:01:04.038Z","avatar_url":"https://github.com/anky2901.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Repo X-Ray\n\n[![CI](https://github.com/anky2901/repo-xray/actions/workflows/ci.yml/badge.svg)](https://github.com/anky2901/repo-xray/actions/workflows/ci.yml)\n\nLocal-first repository intelligence. Point it at a repo and it produces explainable,\ndeterministic reports on security, architecture, dependencies, tests, CI, release readiness,\nmaintainability, performance, git health, code style, business context, and more — plus\ncopy-paste AI prompts and fix suggestions.\n\n- **Local-first:** clones/copies the repo and analyzes it on your machine. No data leaves by default.\n- **Deterministic:** the same input produces byte-identical `scan.json` and reports.\n- **Explainable:** every finding carries evidence, a confidence score, and plain-English reasoning.\n- **Offline-capable:** works from cache with `--offline`; network is only used for CVE/registry lookups.\n\n## Requirements\n\n- Node.js \u003e= 18 (tested on 22)\n- pnpm 10+\n- git on PATH (for scanning GitHub URLs and git-history analysis)\n\n## Setup\n\n```bash\npnpm install\npnpm build\n```\n\nVerify your environment at any time (either form works — see \"The `xray` command\" below):\n\n```bash\nnode apps/cli/dist/index.js doctor\n```\n\n## Quick start\n\nScan a GitHub repo (zero config):\n\n```bash\nxray scan https://github.com/expressjs/express --mode=deep\n```\n\nReports are written to `.xray-reports/` by default. Open `.xray-reports/DASHBOARD.html` in a\nbrowser for the interactive view, or read `REPORT.md` for the summary.\n\n## How to use\n\nA full walkthrough, from install to reading results.\n\n### 1. Install and build\n\n```bash\npnpm install\npnpm build\n```\n\n### 2. Check your environment\n\n```bash\nnode apps/cli/dist/index.js doctor\n```\n\nThis confirms Node, pnpm, git, SQLite, cache access, and disk space. Fix anything it reports as\n`FAIL` before scanning.\n\n### 3. Run your first scan\n\nPick a target — a local folder, a GitHub URL, or a `.zip` archive — and choose a mode. For a full\nreview, use `deep`:\n\n```bash\n# a local project\nnode apps/cli/dist/index.js scan ./path/to/project --mode=deep\n\n# a remote repository\nnode apps/cli/dist/index.js scan https://github.com/expressjs/express --mode=deep\n\n# the current directory\nnode apps/cli/dist/index.js scan . --mode=deep\n```\n\nUse `--output=\u003cdir\u003e` to write reports somewhere other than `.xray-reports/`.\n\n### 4. Read the results\n\nAfter a scan, look at the output directory (default `.xray-reports/`):\n\n- **`DASHBOARD.html`** — open in a browser for the interactive view: score cards, a severity\n  summary, and a filterable findings table. Start here.\n- **`REPORT.md`** — the text summary with the health scorecard and the top findings.\n- **Topic reports** — drill into a specific area: `SECURITY.md`, `DEPENDENCY.md`,\n  `ARCHITECTURE.md`, `TEST_PLAN.md`, `RELEASE.md`, and the rest (full list under\n  [Output files](#output-files-deep-mode)).\n- **`FIXES.md`** — a prioritized, copy-paste list of concrete fixes.\n- **`scan.json`** — the full machine-readable result if you want to script against it.\n\nEvery finding includes the file/line evidence, a confidence score, and a plain-English reason.\n\n### 5. Pick the right mode for the job\n\n- Quick triage or pre-commit: `--mode=quick` (security only, fastest).\n- Full review: `--mode=deep` (all modules).\n- Deep audit: `--mode=paranoid`.\n- Inside a pipeline: `--ci --fail-on=HIGH` (machine output + exit codes).\n\n### 6. Common workflows\n\n```bash\n# Gate a CI build: non-zero exit on HIGH or CRITICAL findings\nnode apps/cli/dist/index.js scan . --ci --fail-on=HIGH\n\n# Quick release-readiness check (release + CI health only)\nnode apps/cli/dist/index.js release-check .\n\n# Generate AI prompts grounded in this repo's real facts\nnode apps/cli/dist/index.js prompts .\n\n# Re-scan without network access, using cached CVE/registry data\nnode apps/cli/dist/index.js scan . --mode=deep --offline\n\n# Compare two past scans from the local history\nnode apps/cli/dist/index.js history \u003crepoId\u003e\nnode apps/cli/dist/index.js compare \u003cscanId1\u003e \u003cscanId2\u003e\n```\n\n\u003e Tip: the examples above use the long form so they work immediately after `pnpm build`. To use\n\u003e the shorter `xray \u003ccommand\u003e` form, see [The `xray` command](#the-xray-command) below.\n\n## The `xray` command\n\nThe CLI package ships a `bin` named `xray`. To use it as a global command:\n\n```bash\npnpm --filter @repo-xray/cli build   # ensure dist is built\npnpm setup                           # one-time: creates pnpm's global bin dir (restart shell after)\npnpm --filter @repo-xray/cli link --global\nxray --help\n```\n\nIf you prefer not to set up a global bin, every command also works via:\n\n```bash\nnode apps/cli/dist/index.js \u003ccommand\u003e\n```\n\nBoth forms are equivalent; the examples below use `xray`.\n\n## Commands\n\n### `scan \u003csource\u003e`\nScan a local path, GitHub URL, or `.zip` archive.\n\n| Option | Description |\n|---|---|\n| `--mode \u003cmode\u003e` | `quick` (security only, fast), `deep` (all modules), `paranoid` (all + extra passes), `ci` (machine output + exit codes). Default: `quick`. |\n| `--output \u003cdir\u003e` | Output directory for reports. Default: `.xray-reports`. |\n| `--offline` | Use only cached data; skip live CVE/registry lookups. |\n| `--ci` | Machine-friendly run with CI exit codes (implies `ci` mode). |\n| `--fail-on \u003cseverity\u003e` | In CI mode, exit non-zero when a finding at or above this severity exists (e.g. `HIGH`). |\n\nExamples:\n\n```bash\n# Fast security-focused pass on the current directory\nxray scan . --mode=quick\n\n# Full analysis of a local project into a custom folder\nxray scan ./my-app --mode=deep --output=reports/\n\n# CI gate: fail the build on HIGH+ findings\nxray scan . --ci --fail-on=HIGH\n\n# Offline re-scan using cached CVE/registry data\nxray scan https://github.com/user/repo --mode=deep --offline\n```\n\nCI exit codes: `0` clean, `1` findings below threshold, `2` HIGH present, `3` CRITICAL present.\n\n### `release-check \u003csource\u003e`\nFast path that runs only release readiness (M17) + CI health (M18). Writes `RELEASE.md`,\n`RELEASE_CHECKLIST.md`, `CI_REPORT.md`.\n\n```bash\nxray release-check . --output=reports/\n```\n\n### `prompts \u003csource\u003e`\nGenerate copy-paste AI prompts grounded in the repo's actual facts. Writes\n`PROMPTS/{dev,bugfix,feature,audit,onboarding}.md`.\n\n```bash\nxray prompts .\n```\n\n### `history [repoId]`, `compare \u003cid1\u003e \u003cid2\u003e`\nQuery and diff past scans stored in the SQLite history (`.xray-reports/xray.db`).\n\n```bash\nxray history \u003crepoId\u003e\nxray compare \u003cscanId1\u003e \u003cscanId2\u003e\n```\n\n### `config`, `doctor`\n`config` prints the resolved configuration; `doctor` runs environment diagnostics.\n\n## Scan modes\n\n| Mode | Modules | Use for |\n|---|---|---|\n| `quick` | Security only | Fast pre-commit / triage |\n| `deep` | All modules | Full review (default recommendation) |\n| `paranoid` | All modules + extra passes | Deep audits |\n| `ci` | All modules, machine output, exit codes | Pipelines |\n\n## Output files (deep mode)\n\n| File | Contents |\n|---|---|\n| `REPORT.md` | Master summary + health scorecard + badge |\n| `DASHBOARD.html` | Interactive, filterable dashboard |\n| `SECURITY.md` | Secrets, dangerous patterns, config issues, CVEs (secrets always masked) |\n| `ARCHITECTURE.md` / `ARCHITECTURE.html` | Import graph, cycles, god files, layering, dead modules |\n| `DEPENDENCY.md` | Vulnerable/duplicate/abandoned/oversized deps, license conflicts |\n| `TEST_PLAN.md` | Coverage, gaps, flaky-test patterns |\n| `RELEASE.md` / `RELEASE_CHECKLIST.md` | Weighted release-readiness scorecard + checklist |\n| `CI_REPORT.md` | Workflow health: tests, pinned actions, secrets, permissions, timeouts |\n| `MAINTAINABILITY.md` | Complexity, file size, comment density, hotspots |\n| `PERFORMANCE.md` | Static performance hotspots |\n| `GIT.md` | Commit velocity, contributors, bus factor, churn hotspots |\n| `CODE_STYLE.md` | Indentation/quote consistency, trailing whitespace, long lines |\n| `BUSINESS.md` | Inferred purpose, domain, users, distribution |\n| `VULN_REPORT.md` | Per-vulnerability fixes (minimal + best-practice + AI prompt + test) |\n| `ADOPTION.md` | Adoption-potential estimate with confidence interval |\n| `FIXES.md` | Consolidated, severity-grouped fix suggestions |\n| `PROMPTS/*.md` | AI prompts grounded in extracted repo facts |\n| `scan.json` | Full structured result (schema 1.0), deterministic |\n| `scan.sarif` | SARIF 2.1.0 for GitHub Code Scanning |\n| `scan.pdf` | Rendered when a Chrome runtime is available (skipped gracefully otherwise) |\n\n## Configuration\n\nZero config works out of the box. To customize, add a `.xrayrc.json` at the repo root, set\n`XRAY_*` environment variables, or pass CLI flags (CLI overrides env overrides file overrides\ndefaults). Common settings: `output.dir`, `cache.dir`, `ignore.patterns`, `github.token`,\n`ai.provider`. Telemetry is always off.\n\nIgnore rules: honors `.gitignore` by default; add repo-specific exclusions in `.xrayignore`.\n\n## Using the SDK\n\nEverything is available programmatically through `@repo-xray/sdk`:\n\n```ts\nimport { XRayPipeline, FileCache, loadConfig, logger, renderDashboard } from '@repo-xray/sdk';\n\nconst config = loadConfig();\nconst result = await new XRayPipeline().run({\n  source: './my-app',\n  mode: 'deep',\n  modules: ['security', 'architecture', 'dependency', 'test-intelligence', 'release', 'ci-health'],\n  config,\n  cache: new FileCache(config.cache.dir),\n  logger,\n});\n\nconsole.log(result.scores);\nconst html = renderDashboard(result); // self-contained dashboard HTML\n```\n\n## Development\n\n```bash\npnpm typecheck   # strict TypeScript across all packages\npnpm lint        # eslint\npnpm test        # vitest\npnpm build       # lint + build all packages\n```\n\nThe repo is a pnpm workspace: `apps/` (cli, web), `packages/` (sdk, core, per-module analyzers,\ncache, storage, export, reporting), and `shared/`. Apps depend only on the SDK; analyzers depend\non `@repo-xray/types`. This boundary is enforced by a test.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanky2901%2Frepo-xray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanky2901%2Frepo-xray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanky2901%2Frepo-xray/lists"}