@@ -188,7 +188,7 @@
     },
     {
       "name": "static-analysis",
-      "version": "1.4.5",
+      "version": "1.5.0",
       "description": "Static analysis toolkit with CodeQL, Semgrep, and SARIF parsing for security vulnerability detection",
       "author": {
         "name": "Axel Mierczuk & Paweł Płatek"
 
@@ -1,6 +1,6 @@
 {
   "name": "static-analysis",
-  "version": "1.4.5",
+  "version": "1.5.0",
   "description": "Static analysis toolkit with CodeQL, Semgrep, and SARIF parsing for security vulnerability detection",
   "author": {
     "name": "Axel Mierczuk & Paweł Płatek"
 
@@ -264,6 +264,8 @@ read from the processes and the JSON they wrote.
 - [ ] Approved plan written to `$OUTPUT_DIR/rulesets.json` at the Step 3 gate, and passed to
       the scanner unchanged
 - [ ] `coveredNothing` from `scans.json` is empty, or listed in the report
+- [ ] `oversized` from `scans.json` is empty, or listed in the report — those files exceed
+      `--max-target-bytes` and no ruleset opened them
 - [ ] Raw per-scan outputs stored in `$OUTPUT_DIR/raw/`
 - [ ] `results.sarif` exists in `$OUTPUT_DIR/results/` and is valid JSON
 - [ ] Important-only mode: post-filter applied before merge, merge run with `--important`, unfiltered results preserved in `raw/`
 
@@ -140,7 +140,33 @@ set would drop real findings from the primary deliverable with nothing downstrea
 
 - **Run all**: no severity flags
 - **Important only**: `--severity WARNING --severity ERROR`
+- **Both**: `--max-target-bytes 20000000` (see below)
 
 That pre-filter is applied by semgrep at scan time, before the metadata post-filter above. A
 rule shipping with CLI severity INFO is dropped by the flag and never reaches the filter that
 would have kept it.
+
+### File Size Limit
+
+semgrep skips any file larger than `--max-target-bytes` and says nothing about it in `--json`
+output: no `paths.skipped` entry, no error, and the file is absent from `paths.scanned`. A 1 MB
+bundle therefore reports `findings: 0` exactly as a file that was opened and found clean does.
+The reason is only reachable through `--verbose`, which the scanner does not use.
+
+`run-scans.sh` sets the limit explicitly at 20,000,000 bytes rather than leaning on semgrep's
+1,000,000-byte default, which generated sources, single-file bundles and legacy monoliths pass
+routinely. Override it with `--max-target-bytes N` when a target holds larger sources, or with
+`--max-target-bytes 0` to lift the limit entirely, which is what semgrep does with a zero. The
+effective value is recorded as `maxTargetBytes` in `scans.json`. Bytes only: semgrep also accepts
+`1.5MB`, and the scanner refuses that form rather than parsing the size a second way to build the
+report below.
+
+Files an `--include` glob selected that are still over the limit are listed as `oversized` in
+`scans.json`, and they belong in the report: a scan that did not open a file has not cleared it.
+Report them as a coverage gap, not as a clean result. Raising the limit re-scans them at the cost
+of memory and time, so a deliberate decision to leave one out is fine as long as it is written
+down.
+
+Cross-language rulesets (`p/security-audit`, `p/secrets`, third-party repos) take no `--include`,
+and semgrep alone decides which files it can parse, so `oversized` cannot enumerate their share
+of the gap. `maxTargetBytes` is in the report so that part can be checked by hand.
@@ -11,6 +11,14 @@ readonly METRICS_OFF="--metrics=off"
 # references/scan-modes.md, not here.
 SEVERITY_FLAGS=(--severity WARNING --severity ERROR)
 readonly DEFAULT_JOBS=4
+# semgrep drops any file larger than --max-target-bytes and reports NOTHING about it: no
+# paths.skipped entry, no error, and the file is simply absent from .paths.scanned. A scan that
+# never opened a 1 MB bundle therefore records `findings: 0` next to a plausible filesScanned
+# count, which is indistinguishable from a file that was opened and found clean. semgrep's own
+# default is 1,000,000 bytes, which generated sources, single-file bundles, vendored blobs and
+# legacy monoliths pass routinely, so the limit is set explicitly here, recorded in scans.json,
+# and the files it still drops are named — see the oversized report below.
+readonly DEFAULT_MAX_TARGET_BYTES=20000000
 
 # A semgrep join rule carries `mode: join` and the `join:` block that mode needs, and requiring
 # both is what keeps the prune below off a rule that merely mentions the words. Each is anchored
@@ -32,12 +40,18 @@ Usage: run-scans.sh --target DIR --output-dir DIR --mode MODE --rulesets FILE [o
   --rulesets FILE    JSON: {"baseline":[...], "<language>":[...], "third_party":["https://..."]}
   --pro              add --pro to every command (Semgrep Pro engine)
   --jobs N           concurrent semgrep processes (default 4)
+  --max-target-bytes N
+                     skip files larger than N bytes; 0 means no limit, as it does in
+                     semgrep (default 20000000). semgrep's own default is 1000000 and
+                     it drops the file with no trace in the JSON
   --dry-run          print the commands that would run, then exit; clones nothing
 
 Writes OUTPUT_DIR/scans.json:
   {scans:[{lang,ruleset,json,sarif,findings,filesScanned,partial,exitCode}],
-   failed:[...], skipped:[...], unscoped:[lang], alsoShared:["lang/ruleset"]}
+   failed:[...], skipped:[...], unscoped:[lang], alsoShared:["lang/ruleset"],
+   maxTargetBytes:N, oversized:[path]}
   partial is a scan that wrote complete output while some of its rules failed to compile.
+  oversized names the files an --include glob selected that are too large for semgrep to open.
 USAGE
 }
 
@@ -145,6 +159,7 @@ count_lines() {
 
 TARGET="" OUTPUT_DIR="" MODE="" RULESETS_FILE="" PRO="" DRY_RUN=""
 JOBS=$DEFAULT_JOBS
+MAX_TARGET_BYTES=$DEFAULT_MAX_TARGET_BYTES
 while [ $# -gt 0 ]; do
   case "$1" in
     --target)
@@ -167,6 +182,10 @@ while [ $# -gt 0 ]; do
       JOBS=${2:-}
       shift 2
       ;;
+    --max-target-bytes)
+      MAX_TARGET_BYTES=${2:-}
+      shift 2
+      ;;
     --pro)
       PRO=1
       shift
@@ -198,6 +217,12 @@ fi
 jq -e . "$RULESETS_FILE" >/dev/null 2>&1 || die "--rulesets is not valid JSON: $RULESETS_FILE"
 case "$JOBS" in '' | *[!0-9]*) die "--jobs must be a positive integer, got '${JOBS}'" ;; esac
 [ "$JOBS" -ge 1 ] || die "--jobs must be at least 1"
+# Bytes only. semgrep also takes '1.5MB', but the oversized report below has to compare the
+# limit against a file size, so a suffixed value would have to be parsed twice and the two
+# readings could disagree. 0 is accepted and means no limit, which is what semgrep does with it.
+case "$MAX_TARGET_BYTES" in
+  '' | *[!0-9]*) die "--max-target-bytes must be a whole number of bytes, got '${MAX_TARGET_BYTES}'" ;;
+esac
 
 # Both paths resolve the same way before being compared. Resolving only one makes the equality
 # and inside-the-target checks miss on any symlinked path (every /var path on macOS), and the
@@ -294,11 +319,13 @@ UNSCOPED="$WORK/unscoped.txt"
 # exactly like p/gosec would have. semgrep counts what it opened in .paths.scanned, so the two
 # can be told apart and the ones that covered nothing named.
 COVERED_NOTHING="$WORK/covered-nothing.txt"
+OVERSIZED="$WORK/oversized.txt"
 : >"$SCAN_LIST"
 : >"$SKIPPED"
 : >"$ALSO_SHARED"
 : >"$UNSCOPED"
 : >"$COVERED_NOTHING"
+: >"$OVERSIZED"
 
 # Stems are the filename half of every output path and the key results are matched on, so a
 # collision would let one scan's result be read as another's.
@@ -522,6 +549,7 @@ build_argv() {
   ARGV=(semgrep)
   [ -z "$PRO" ] || ARGV+=(--pro)
   ARGV+=("$METRICS_OFF")
+  ARGV+=(--max-target-bytes "$MAX_TARGET_BYTES")
   [ "$MODE" != "important-only" ] || ARGV+=("${SEVERITY_FLAGS[@]}")
   # Unquoted on purpose: includes is a space-separated glob list and must word-split here.
   # shellcheck disable=SC2086
@@ -554,6 +582,59 @@ if [ -n "$DRY_RUN" ]; then
   exit 0
 fi
 
+# ------------------------------------------------------------- oversized files
+# What semgrep refused to open, as against what it opened and found clean. filesScanned counts
+# the second and nothing in the JSON reports the first, so a file over the limit reads as a file
+# that is clean. Named here for the reason coveredNothing and excludePattern are: a gap only
+# stderr knows about is a gap the report calls coverage.
+#
+# Scoped to the --include globs this run actually passes, because those are the files a scan
+# claimed to cover. The cross-language rulesets take no --include and semgrep decides for itself
+# which files it can parse, so their share of the gap is not enumerable from here;
+# references/scan-modes.md says so, and maxTargetBytes is in the report for a reader to check by
+# hand. includes_for only ever emits basename patterns, which is what makes -name enough.
+scoped_globs() {
+  cut -f5 "$SCAN_LIST" | tr ' ' '\n' | grep -v '^$' | sort -u | tr '\n' ' '
+}
+
+# The globs are read into an array rather than left to word-split: unquoted expansion is
+# pathname expansion too, and these patterns are meant to match under the target, not the CWD.
+find_oversized() { # <limit> <globs> -> paths relative to TARGET, one per line
+  local limit=$1 globs=$2 g f
+  local gl nameargs prune
+  # 0 disables semgrep's own filter, so nothing is dropped for its size and there is no gap to
+  # report. Guarded rather than left to `find -size +0c`, which matches every non-empty file.
+  [ "$limit" -gt 0 ] || return 0
+  gl=()
+  nameargs=()
+  prune=()
+  [ -n "$(printf '%s' "$globs" | tr -d ' ')" ] || return 0
+  IFS=' ' read -r -a gl <<<"$globs"
+  for g in ${gl[@]+"${gl[@]}"}; do
+    [ -n "$g" ] || continue
+    if [ ${#nameargs[@]} -eq 0 ]; then
+      nameargs=(-name "$g")
+    else
+      nameargs+=(-o -name "$g")
+    fi
+  done
+  [ ${#nameargs[@]} -gt 0 ] || return 0
+  # The output directory is already --exclude'd from every scan, so a file inside it is not a
+  # coverage gap; listing it would put this run's own raw JSON in the report.
+  [ -z "$EXCLUDE_PATTERN" ] || prune=(-name "$EXCLUDE_PATTERN" -prune -o)
+  find "$TARGET" ${prune[@]+"${prune[@]}"} -type f -size +"${limit}"c \
+    \( "${nameargs[@]}" \) -print 2>/dev/null | while IFS= read -r f; do
+    printf '%s\n' "${f#"$TARGET"/}"
+  done | sort
+}
+
+OVERSIZED_LIST=$(find_oversized "$MAX_TARGET_BYTES" "$(scoped_globs)")
+printf '%s\n' "$OVERSIZED_LIST" >"$OVERSIZED"
+if [ -n "$OVERSIZED_LIST" ]; then
+  echo "note: $(count_lines "$OVERSIZED_LIST") file(s) exceed --max-target-bytes" >&2
+  echo "      ($MAX_TARGET_BYTES) and no scan will open them; see .oversized in scans.json." >&2
+fi
+
 # ------------------------------------------------------------------- run the scans
 # Batched rather than a rolling slot count, because `wait -n` needs bash 4.3 and this has to run
 # on the bash 3.2 that ships with macOS. semgrep holds the rules and the scanned ASTs in memory,
@@ -680,15 +761,18 @@ jq -n \
   --rawfile alsoSharedRaw "$ALSO_SHARED" \
   --rawfile unscopedRaw "$UNSCOPED" \
   --rawfile coveredNothingRaw "$COVERED_NOTHING" \
+  --rawfile oversizedRaw "$OVERSIZED" \
+  --argjson maxTargetBytes "$MAX_TARGET_BYTES" \
   '{
      outputDir: $outputDir, rawDir: $rawDir, reposPath: $reposPath, mode: $mode, pro: $pro,
-     excludePattern: $excludePattern,
+     excludePattern: $excludePattern, maxTargetBytes: $maxTargetBytes,
      scans: $scans, failed: $failed,
      skipped: ($skippedRaw | split("\n") | map(select(length > 0)) | map(split("\t"))
                | map({ruleset: .[0], reason: (.[1] // "clone failed")})),
      alsoShared: ($alsoSharedRaw | split("\n") | map(select(length > 0)) | unique),
      unscoped: ($unscopedRaw | split("\n") | map(select(length > 0)) | unique),
-     coveredNothing: ($coveredNothingRaw | split("\n") | map(select(length > 0)) | unique)
+     coveredNothing: ($coveredNothingRaw | split("\n") | map(select(length > 0)) | unique),
+     oversized: ($oversizedRaw | split("\n") | map(select(length > 0)) | unique)
    }' >"$OUTPUT_ROOT/scans.json"
 
 n_ok=$(jq '.scans | length' "$OUTPUT_ROOT/scans.json")
 
@@ -323,6 +323,8 @@ and the severity flags are all its job, not yours. It writes `$OUTPUT_DIR/scans.
 | `unscoped` | Languages with no `--include` globs, which ran against every file |
 | `alsoShared` | Rulesets dropped from a language because the same ruleset is already running unscoped over the whole target. Coverage is unaffected; report them so a per-ruleset accounting adds up |
 | `excludePattern` | Set when the output directory sits inside the target: the pattern passed as `--exclude` to every scan, or `""`. semgrep matches it anywhere in the tree, so `out` also drops `src/out/`. **Must be shown when non-empty.** |
+| `maxTargetBytes` | The `--max-target-bytes` every scan ran with. semgrep opens no file larger than this |
+| `oversized` | Files an `--include` glob selected that are larger than `maxTargetBytes`. semgrep skipped them with no `paths.skipped` entry and no error, so they report 0 findings exactly like a file that was opened and found clean. A scan that did not open a file has not cleared it. **Must be shown.** |
 | `reposPath` | The clone directory Step 5 deletes |
 
 **A non-zero exit means no scan succeeded.** The script exits 1 when `scans` is empty, so a run
@@ -439,6 +441,12 @@ one finding flagged by two rulesets is one row in the merge and two in that sum]
   looked at anything. Check the plan against the languages Step 1 detected: this is what a
   ruleset for a language the target does not contain looks like
 
+### Too Large To Scan:
+[omit when oversized is empty]
+- <path> — larger than maxTargetBytes, so semgrep never opened it and no ruleset covered it.
+  Not a clean result: re-run with a higher --max-target-bytes, or say in the report that the
+  file was left unscanned
+
 ### Missing From The Merge:
 [omit when the merge printed no "unparseable:" line]
 - <file> — the scan succeeded and is counted in scans.json, but its SARIF could not be parsed,
 
@@ -16,7 +16,7 @@ command -v uv >/dev/null 2>&1 || {
 
 PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 SCRIPT="$PLUGIN_ROOT/skills/semgrep/scripts/run-scans.sh"
-readonly EXPECTED_ASSERTIONS=93
+readonly EXPECTED_ASSERTIONS=104
 
 command -v jq >/dev/null 2>&1 || {
   echo "run_scan_tests.sh: jq not found — required" >&2
@@ -574,6 +574,81 @@ ok "$([ -e "$WORK/filter/results.sarif" ] && echo 1 || echo 0)" \
 contains "$MERGE_ERR" "python-broken-important.json" \
   "the merge error must name the scan that has no filtered JSON"
 
+# ---------------------------------------------------------------------- the file size limit
+# semgrep skips any file over --max-target-bytes and writes nothing about it: no paths.skipped
+# entry, no error, and the file absent from paths.scanned. `findings: 0` for a file that was
+# never opened reads exactly like a file that was opened and found clean.
+echo "→ the file size limit"
+
+unset STUB_PATHS
+export STUB_RC=0 STUB_RESULTS=''
+
+out=$(dry "$BASIC")
+n=$(printf '%s\n' "$out" | grep -c -- '--max-target-bytes 20000000')
+eq "$n" "2" "an explicit limit must be on every command rather than semgrep's 1 MB default"
+
+out=$(dry "$BASIC" --max-target-bytes 12345)
+n=$(printf '%s\n' "$out" | grep -c -- '--max-target-bytes 12345')
+eq "$n" "2" "an overridden limit must reach every command"
+
+# semgrep takes '1.5MB' as well as a byte count, but the oversized report has to compare the
+# limit against a file size, so a suffixed value is refused rather than parsed a second way.
+msg=$(fails bash "$SCRIPT" --target "$TARGET" --output-dir "$WORK/out" --mode run-all \
+  --rulesets "$BASIC" --max-target-bytes 5MB --dry-run)
+ok $? "a suffixed --max-target-bytes must be rejected rather than reinterpreted"
+contains "$msg" "whole number of bytes" "the message must say what form the value takes"
+
+# semgrep reads 0 as no limit at all, so it is passed through rather than refused.
+out=$(dry "$BASIC" --max-target-bytes 0)
+n=$(printf '%s\n' "$out" | grep -c -- '--max-target-bytes 0')
+eq "$n" "2" "zero must reach every command, since semgrep reads it as no limit"
+
+# The files over the limit are named, because filesScanned counts what semgrep opened and can
+# say nothing about what it refused. A small limit over small fixtures: the behaviour does not
+# depend on the size, and a suite that wrote a 20 MB file to prove it would earn nothing.
+BIGT="$WORK/bigproj"
+mkdir -p "$BIGT/src" "$BIGT/out"
+pad='padding that exists only to push this fixture past the limit
+'
+big="$pad$pad$pad$pad"
+big="$big$big"
+printf 'x = 1\n' >"$BIGT/src/small.py"
+printf '%s' "$big" >"$BIGT/src/big.py"
+printf '%s' "$big" >"$BIGT/src/big.txt"
+printf '%s' "$big" >"$BIGT/out/vendored.py"
+
+PATH="$WORK/bin:$PATH" bash "$SCRIPT" --target "$BIGT" --output-dir "$BIGT/out" \
+  --mode run-all --rulesets "$ONE" --jobs 2 --max-target-bytes 100 >/dev/null 2>&1
+BIGJSON="$BIGT/out/scans.json"
+ok "$([ -f "$BIGJSON" ] && echo 0 || echo 1)" "a target holding oversized files must still write scans.json"
+eq "$(jq -r '.maxTargetBytes' "$BIGJSON" 2>/dev/null || echo NOFILE)" "100" \
+  "scans.json must record the limit the scans actually ran with"
+# One path exactly: small.py is under the limit, big.txt matches no --include glob, and
+# out/vendored.py sits in the excluded output directory, so none of the three is a coverage gap.
+eq "$(jq -r '.oversized | join(",")' "$BIGJSON" 2>/dev/null || echo NOFILE)" "src/big.py" \
+  "a file over the limit that an --include glob selected must be named in oversized"
+
+PATH="$WORK/bin:$PATH" bash "$SCRIPT" --target "$BIGT" --output-dir "$WORK/big2" \
+  --mode run-all --rulesets "$ONE" --jobs 2 --max-target-bytes 100000 >/dev/null 2>&1
+eq "$(jq '.oversized | length' "$WORK/big2/scans.json" 2>/dev/null || echo NOFILE)" "0" \
+  "a limit nothing exceeds must leave oversized empty"
+
+# A cross-language ruleset takes no --include and semgrep alone decides which files it can
+# parse, so its share of the gap is not enumerable here. Pinned so the limitation stays a
+# decision rather than becoming a surprise.
+# No limit means nothing was dropped for its size, so the report must stay empty rather than
+# listing every non-empty file the globs matched — which is what `find -size +0c` would give.
+PATH="$WORK/bin:$PATH" bash "$SCRIPT" --target "$BIGT" --output-dir "$WORK/big4" \
+  --mode run-all --rulesets "$ONE" --jobs 2 --max-target-bytes 0 >/dev/null 2>&1
+eq "$(jq '.oversized | length' "$WORK/big4/scans.json" 2>/dev/null || echo NOFILE)" "0" \
+  "a disabled limit must leave oversized empty, not list every file"
+
+BASEONLY=$(plan baseonly '{"baseline":["p/security-audit"],"third_party":[]}')
+PATH="$WORK/bin:$PATH" bash "$SCRIPT" --target "$BIGT" --output-dir "$WORK/big3" \
+  --mode run-all --rulesets "$BASEONLY" --jobs 2 --max-target-bytes 100 >/dev/null 2>&1
+eq "$(jq '.oversized | length' "$WORK/big3/scans.json" 2>/dev/null || echo NOFILE)" "0" \
+  "a plan with no --include globs must leave oversized empty by design"
+
 TOTAL=$((PASS + FAIL))
 echo
 echo "$PASS passed, $FAIL failed, $TOTAL run"
Original file line number	Diff line number	Diff line change
`@@ -188,7 +188,7 @@`
`188`	`188`	`},`
`189`	`189`	`{`
`190`	`190`	`"name": "static-analysis",`
`191`		`- "version": "1.4.5",`
	`191`	`+ "version": "1.5.0",`
`192`	`192`	`"description": "Static analysis toolkit with CodeQL, Semgrep, and SARIF parsing for security vulnerability detection",`
`193`	`193`	`"author": {`
`194`	`194`	`"name": "Axel Mierczuk & Paweł Płatek"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "static-analysis",`
`3`		`- "version": "1.4.5",`
	`3`	`+ "version": "1.5.0",`
`4`	`4`	`"description": "Static analysis toolkit with CodeQL, Semgrep, and SARIF parsing for security vulnerability detection",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Axel Mierczuk & Paweł Płatek"`