{"_id":"@bwawan/xray","name":"@bwawan/xray","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bwawan/xray","version":"0.1.0","type":"module","bin":{"xray":"src/cli.js"},"scripts":{"test":"vitest run","test:watch":"vitest run --watch","test:coverage":"vitest run --coverage","mutate":"mutagen --incremental --progress --parallel 8 --json reports/mutation/all.json","mutate:dry":"mutagen --all --dry-run"},"license":"MIT","dependencies":{"acorn":"^8.16.0","acorn-jsx":"^5.3.2"},"devDependencies":{"@vitest/coverage-v8":"^4.1.5","@bwawan/mutagen":"^0.1.0","vitest":"^4.1.5"},"gitHead":"f728d66943a7a8ba604ec9ce147359cc49a51046","_id":"@bwawan/xray@0.1.0","description":"Module index generator for JavaScript and TypeScript projects. Produces a JSON map of every source file with exports, dependencies, dependents, associated test files, and line counts.","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-i4CzKdrDFYHni5r9KcS3CN307RkVD5nSFfJBKIJ0Xlanvg87V2uR5pQutNwJ/Dm93iinGS38D+xTu2qUQ1XrXQ==","shasum":"d38dbc00e42006eb991d30ab6c5a17dc828dde44","tarball":"https://registry.npmjs.org/@bwawan/xray/-/xray-0.1.0.tgz","fileCount":32,"unpackedSize":132683,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC1OIHfUKtOyY1UD+fUIVgs6qpfAG6PSkmdwnbgJZOjugIhANwXxN49dH4XVCl4Pr2KvoG8TZXIPsXYtDxSDRD6wda1"}]},"_npmUser":{"name":"bwawan","email":"bwancor@gmail.com"},"directories":{},"maintainers":[{"name":"bwawan","email":"bwancor@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xray_0.1.0_1777146394479_0.3047454194070469"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T19:46:34.256Z","0.1.0":"2026-04-25T19:46:34.614Z","modified":"2026-04-25T19:46:34.837Z"},"maintainers":[{"name":"bwawan","email":"bwancor@gmail.com"}],"description":"Module index generator for JavaScript and TypeScript projects. Produces a JSON map of every source file with exports, dependencies, dependents, associated test files, and line counts.","license":"MIT","readme":"# @bwawan/xray\n\nModule index generator for JavaScript and TypeScript projects. Produces a JSON map of every source file with exports, dependencies, dependents, associated test files, and line counts.\n\nDesigned to help AI agents orient themselves in a codebase without reading every file.\n\n## Installation\n\n```bash\nnpm install -g @bwawan/xray\n```\n\n## Usage\n\n```bash\n# Scan current directory, output JSON to stdout\nxray\n\n# Scan a specific directory\nxray backend/\n\n# Write output to a file\nxray backend/ -o index.json\n\n# Show detail for a single file\nxray backend/ --file src/handlers/feed.js\n\n# Find all files that import a given module\nxray backend/ --dependents-of src/db.js\n\n# Find all direct and transitive dependents\nxray backend/ --dependents-of src/db.js --transitive\n\n# Find all test files affected by a change\nxray backend/ --tests-for src/db.js\n\n# Find all modules a given file imports\nxray backend/ --dependencies-of src/db.js\n\n# List just file paths (token-efficient for agents)\nxray backend/ --files-only\n\n# Scan only specific directories\nxray backend/ --include src --include shared\n\n# Exclude directories from scan\nxray backend/ --exclude coverage --exclude dist\n```\n\n## Output Format\n\nxray outputs a JSON object keyed by relative file path. Each entry contains:\n\n| Field          | Type       | Description                                       |\n|----------------|------------|---------------------------------------------------|\n| `exports`      | `string[]` | Named and default exports (`'default'` for default)|\n| `reExports`    | `string[]` | Star re-export sources (`export * from '...'`)     |\n| `dependencies` | `string[]` | Modules this file imports (project-relative paths) |\n| `dependents`   | `string[]` | Files that import this module                      |\n| `tests`        | `string[]` | Associated test files (by naming convention)       |\n| `lines`        | `number`   | Total line count of the source file                |\n\nExample output:\n\n```json\n{\n  \"src/handlers/feed.js\": {\n    \"exports\": [\"feedHandler\"],\n    \"reExports\": [],\n    \"dependencies\": [\"src/db/instance.js\", \"src/shared/index.js\"],\n    \"dependents\": [\"src/routes.js\"],\n    \"tests\": [\"tests/handlers/feed.test.js\"],\n    \"lines\": 32\n  },\n  \"src/db/instance.js\": {\n    \"exports\": [\"db\", \"query\"],\n    \"reExports\": [],\n    \"dependencies\": [],\n    \"dependents\": [\"src/handlers/feed.js\", \"src/handlers/auth.js\"],\n    \"tests\": [\"tests/db/instance.test.js\"],\n    \"lines\": 18\n  }\n}\n```\n\n## Options\n\n| Flag                        | Description                                          |\n|-----------------------------|------------------------------------------------------|\n| `[dir]`                     | Root directory to scan (default: `.`)                |\n| `-o, --output <file>`       | Write JSON to a file instead of stdout               |\n| `--file <path>`             | Show detail for a single source file                 |\n| `--dependents-of <path>`    | List files that import the given module               |\n| `--transitive`              | Expand `--dependents-of` to full transitive closure   |\n| `--tests-for <path>`        | List test files for target and its transitive dependents |\n| `--dependencies-of <path>`  | List modules imported by the given file               |\n| `--files-only`              | Output only file paths as a JSON array               |\n| `--include <dir>`           | Scan only this directory (repeatable)                |\n| `--exclude <dir>`           | Skip directory during scan (repeatable)              |\n| `--compact`                 | Force compact (single-line) JSON output              |\n| `--pretty`                  | Force pretty-printed JSON output                     |\n| `--help, -h`                | Show help message                                    |\n| `--version, -v`             | Show version                                         |\n\n`--file`, `--dependents-of`, `--dependencies-of`, and `--tests-for` are mutually exclusive query flags. Only one may be used per invocation.\n\n## Exit Codes\n\n| Code | Meaning                                |\n|------|----------------------------------------|\n| `0`  | Success                                |\n| `1`  | Error (unknown flags, conflicting queries, or bad directory) |\n\n## Configuration\n\nxray looks for `xray.config.js` in the scan directory. The config file should export a default object with any of the following fields:\n\n| Field          | Type       | Default                              | Description                      |\n|----------------|------------|--------------------------------------|----------------------------------|\n| `extensions`   | `string[]` | `['.js', '.jsx', '.ts', '.tsx']`     | File extensions to scan          |\n| `exclude`      | `string[]` | `[]`                                 | Directories to exclude           |\n| `include`      | `string[]` | `[]`                                 | Directories to include (all if empty) |\n| `testPatterns` | `string[]` | `['tests/**/*.{test,spec}.*', ...]`  | Glob patterns for test file discovery |\n\nExample:\n\n```js\nexport default {\n  extensions: ['.js', '.jsx'],\n  exclude: ['coverage', 'dist'],\n  include: ['src', 'shared']\n}\n```\n\nCLI flags override config values: `--include` replaces config `include`, `--exclude` merges with config `exclude`.\n\n**Note:** xray executes `xray.config.js` via dynamic `import()`. Only scan directories you trust.\n\n## Examples\n\n### Full project scan\n\n```bash\nxray backend/\n```\n\nScans all JavaScript/TypeScript files under `backend/` and prints the full index to stdout.\n\n### Write index to a file\n\n```bash\nxray backend/ -o xray-index.json\n```\n\n### Find what imports a module\n\n```bash\nxray backend/ --dependents-of src/db/instance.js\n```\n\nReturns the subset of the index showing only files that depend on `src/db/instance.js`. Useful for understanding the blast radius of a change.\n\n### Find all transitive dependents\n\n```bash\nxray backend/ --dependents-of src/db/instance.js --transitive\n```\n\nWalks the full reverse dependency graph. If A imports B imports C, `--dependents-of C --transitive` returns both B and A.\n\n### Find what a module imports\n\n```bash\nxray backend/ --dependencies-of src/handlers/feed.js\n```\n\nReturns the full index entry for that file. Useful for tracing data flow.\n\n### Single file detail\n\n```bash\nxray backend/ --file src/handlers/feed.js\n```\n\nReturns the full index entry for one file: its exports, dependencies, dependents, tests, and line count.\n\n### List files only\n\n```bash\nxray backend/ --files-only\n```\n\nReturns a sorted JSON array of file paths. Token-efficient for agents that just need to orient before drilling into specific files.\n\n## Gas Town Integration\n\nxray is built for AI agent workflows in Gas Town. Agents use xray to:\n\n- **Orient quickly** -- scan an unfamiliar codebase and understand its module structure without reading every file.\n- **Scope changes** -- before modifying a module, check `--dependents-of` to understand what will be affected.\n- **Find tests** -- `--tests-for` returns all test files affected by a change, including tests for transitive dependents.\n- **Trace dependencies** -- `--dependencies-of` shows the import chain, helping agents understand data flow and module boundaries.\n- **Estimate effort** -- the `lines` field gives a quick sense of module size before committing to read it.\n- **Minimize tokens** -- `--files-only` returns just file paths for quick orientation before targeted queries.\n\nTypical agent workflow:\n\n```bash\n# 1. Orient: what files are in this project?\nxray backend/ --files-only\n\n# 2. Before changing a file, check its blast radius\nxray backend/ --dependents-of src/db/instance.js --transitive\n\n# 3. After changes, run only affected tests\nxray backend/ --tests-for src/db/instance.js\n```\n\nThis replaces ad-hoc `grep` and `find` commands with structured, reliable module metadata.\n\n## Development\n\n### Setup\n\n    # Install Node\n    brew install node\n\n    # Install Dependencies\n    npm install\n\n### Useful Commands\n\n    # Run tests once\n    npm run test\n\n    # Run tests (auto)\n    npm run test:watch\n\n    # Run test coverage\n    npm run test:coverage\n\n    # Run mutation tests\n    npm run mutate\n\n    # Dry Run mutation tests\n    npm run mutate:dry\n\n\n### Release\n\n1. Run tests: `npm test`\n2. Run mutation tests: `npm run mutate`\n3. Update version in `package.json`\n4. Update `CHANGELOG.md`\n5. Tag: `git tag vx.x.x`\n6. Push: `git push && git push --tags`\n7. Publish: `npm publish --access public`\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-6c3c8fccf7bb9713c7672a79cb4ff52b"}