{"_id":"@barissozudogru/docker-context-scout","name":"@barissozudogru/docker-context-scout","dist-tags":{"latest":"0.4.0"},"versions":{"0.4.0":{"name":"@barissozudogru/docker-context-scout","version":"0.4.0","description":"Analyze Docker build context and optimize .dockerignore","type":"module","bin":{"docker-context-scout":"dist/cli.js"},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"npm run build && node --test test/*.test.js"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"repository":{"type":"git","url":"git+https://github.com/barissozudogru/docker-context-scout.git"},"keywords":["docker","dockerignore","build-context","optimization","cli"],"author":{"name":"Baris Sozudogru"},"license":"MIT","engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^25.5.0","typescript":"^5.9.3"},"gitHead":"5a24fecf75c22d43c7d7dbe5c02d3cfcd62a824c","_id":"@barissozudogru/docker-context-scout@0.4.0","bugs":{"url":"https://github.com/barissozudogru/docker-context-scout/issues"},"homepage":"https://github.com/barissozudogru/docker-context-scout#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-/x0msENykzX+io+RsIKA+n/r+AIayGmEjLUkzrBmOFPvvi/J04OMLQpDt+AgmzDuNL3ybRFZe+Xd4RE6QNM30Q==","shasum":"1a2a14e3102c1b0483626cbc9a7deb5a341bbf0b","tarball":"https://registry.npmjs.org/@barissozudogru/docker-context-scout/-/docker-context-scout-0.4.0.tgz","fileCount":9,"unpackedSize":32274,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC1gDfvTvDrii2Ren4C2bDRn1YF8GsMI66yM+s8VtKjbAIgA6ZItn/O5tM/Dhg/Ya/ZBotI6LQnSUSA51fNeb0sXMI="}]},"_npmUser":{"name":"barissozudogru","email":"barissozudogru@gmail.com"},"directories":{},"maintainers":[{"name":"barissozudogru","email":"barissozudogru@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/docker-context-scout_0.4.0_1787176151675_0.4706912111517201"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-19T21:49:11.558Z","0.4.0":"2026-08-19T21:49:11.845Z","modified":"2026-08-19T21:49:12.067Z"},"maintainers":[{"name":"barissozudogru","email":"barissozudogru@gmail.com"}],"description":"Analyze Docker build context and optimize .dockerignore","homepage":"https://github.com/barissozudogru/docker-context-scout#readme","keywords":["docker","dockerignore","build-context","optimization","cli"],"repository":{"type":"git","url":"git+https://github.com/barissozudogru/docker-context-scout.git"},"author":{"name":"Baris Sozudogru"},"bugs":{"url":"https://github.com/barissozudogru/docker-context-scout/issues"},"license":"MIT","readme":"# docker-context-scout\n\nFind out what Docker is sending as build context and cut it down to size.\n\nRun without installing:\n\n```bash\nnpx @barissozudogru/docker-context-scout\n```\n\nEvery time you run `docker build`, Docker compresses and streams your entire project directory to the build daemon before a single instruction executes. On a typical Node.js or Python project it is not uncommon to send 400 MB or more of `node_modules`, `.git`, and build artifacts that your final image doesn't need. This slows down builds because Docker re-uploads the full context even for layer-cache hits, risks baking secrets like `.env` files or Terraform state into image layers, and creates unnecessarily large images.\n\ndocker-context-scout walks your project, measures each entry, cross-references your existing `.dockerignore`, and tells you exactly what is bloating your build context and how to fix it. A single `--fix` flag writes the `.dockerignore` rules for you.\n\n## Usage\n\n```\ndocker-context-scout [path] [options]\n\nArguments:\n  path                    Directory to analyze (default: current directory)\n\nOptions:\n  --fix                   Append suggested rules to .dockerignore\n  --json                  Output results as JSON (for CI pipelines)\n  --threshold <MB>        Only show entries above this size in MB\n  --version, -v           Show version number\n  --help, -h              Show help\n```\n\n### Analyze the current directory\n\n```bash\ndocker-context-scout\n```\n\n### Analyze a specific project\n\n```bash\ndocker-context-scout ./my-app\n```\n\n### Apply suggestions automatically\n\n```bash\ndocker-context-scout --fix\n```\n\n### Filter noise - only show entries above 10 MB\n\n```bash\ndocker-context-scout --threshold 10\n```\n\n---\n\n## Options\n\n| Option | Description | Default |\n|---|---|---|\n| `path` | Directory to analyze | Current working directory |\n| `--fix` | Append suggested rules to `.dockerignore` (creates it if absent) | Off |\n| `--json` | Emit machine-readable JSON to stdout | Off |\n| `--threshold <MB>` | Hide entries smaller than this threshold | Show all |\n| `--version`, `-v` | Print version and exit | - |\n| `--help`, `-h` | Print usage and exit | - |\n\n---\n\n## Example Output\n\n```\n  Docker Context Scout\n------------------------------------------------------------\n  Path:        /Users/you/my-app\n  Total size:  487.20 MB (6 241 files)\n  .dockerignore: not found\n\n  Top items by size:\n------------------------------------------------------------\n  [dir ]  node_modules                                342.00 MB\n  [dir ]  .git                                         89.00 MB\n  [dir ]  dist                                         38.10 MB\n  [dir ]  coverage                                     14.80 MB\n  [file]  db/seed-data.sql                              2.90 MB\n  [dir ]  .next                                         0.40 MB\n\n  Suggested .dockerignore rules:\n------------------------------------------------------------\n  node_modules               saves ~   342.00 MB  Dependencies are reinstalled during build\n  .git                       saves ~    89.00 MB  Git metadata is never needed in Docker images\n  dist                       saves ~    38.10 MB  Build artifacts should be produced inside the Docker build\n  coverage                   saves ~    14.80 MB  Test coverage reports are not needed in production images\n  .next                      saves ~     0.40 MB  Next.js build cache should be regenerated inside the Docker build\n\n------------------------------------------------------------\n  Estimated context after optimization: 12.00 MB\n  Potential reduction: 97.5% (475.20 MB)\n```\n\nAfter running `--fix`, a `.dockerignore` is created with all suggested rules.\n\n---\n\n## What It Detects\n\n| Pattern | Reason |\n|---|---|\n| `.git` | Git metadata is never needed in Docker images |\n| `node_modules` | Dependencies are reinstalled during build via npm/yarn/pnpm |\n| `__pycache__` / `*.pyc` | Python bytecode cache is regenerated at runtime |\n| `.env*` | Environment files must never be baked into images |\n| `*.md` | Documentation files are not needed at runtime |\n| `test` / `tests` / `__tests__` | Test files and directories are not needed in production images |\n| `.vscode` / `.idea` | Editor configuration has no purpose inside containers |\n| `dist` / `build` | Build artifacts should be produced inside the Docker build |\n| `coverage` | Test coverage reports are not needed in production images |\n| `.next` / `.nuxt` | Framework build caches should be regenerated inside the Docker build |\n| `*.log` | Log files are generated at runtime and must not be baked in |\n| `.DS_Store` / `Thumbs.db` | OS metadata files are irrelevant in Linux containers |\n| `.terraform` / `*.tfstate*` | Terraform state may contain secrets and is not needed at runtime |\n\n---\n\n## CI Integration\n\nUse `--json` to gate builds on context size in any CI pipeline.\n\n### GitHub Actions - fail if context exceeds 50 MB\n\n```yaml\n- name: Check Docker build context\n  run: |\n    npx @barissozudogru/docker-context-scout --json > context.json\n    SIZE=$(node -e \"const r=require('./context.json'); process.exit(r.totalSizeMB > 50 ? 1 : 0)\")\n  shell: bash\n```\n\n### Extract reduction percentage\n\n```bash\ndocker-context-scout --json | jq '.reductionPercentage'\n```\n\n### Full JSON schema\n\n```json\n{\n  \"analyzedPath\": \"/absolute/path\",\n  \"totalSizeBytes\": 510980096,\n  \"totalSizeMB\": 487.20,\n  \"fileCount\": 6241,\n  \"dockerfileFound\": true,\n  \"existingDockerignoreRules\": [],\n  \"topOffenders\": [\n    { \"path\": \"node_modules\", \"size\": 358612992, \"isDirectory\": true }\n  ],\n  \"suggestedRules\": [\n    {\n      \"pattern\": \"node_modules\",\n      \"reason\": \"Dependencies are reinstalled during build via npm/yarn/pnpm install\",\n      \"estimatedSavingsBytes\": 358612992\n    }\n  ],\n  \"estimatedReducedSizeBytes\": 12582912,\n  \"estimatedReducedSizeMB\": 12.00,\n  \"reductionPercentage\": 97.5\n}\n```\n\n---\n\n## Exit Codes\n\n| Code | Meaning |\n|---|---|\n| `0` | Analysis completed successfully |\n| `1` | Error - invalid path, unreadable directory, or bad argument |\n\n---\n\n## License\n\n[MIT](./LICENSE) - Baris Sozudogru\n","readmeFilename":"README.md","_rev":"1-5fae607711681ea147807db89a6be987"}