map: adapter summaries — argument roles and narrow candidate families

[patchstackdave]

Track 2, step 1. The review recommended small per-library adapter summaries before any whole-program dataflow engine, because which argument received the value decides which mitigation class applies. This is the gate that lets ruleGeneratable ever be true.

Stacked on #124 (which stacks on #123). Merge order: #123 → #124 → this.

Argument roles

Every flow now reports argumentRole, from a table keyed by sink kind so an overloaded name (get) can't be read as the wrong thing:

exec(command) · execFile(file, args) · spawn(command, args)
fetch(url, init) · axios.get(url, options) · axios.post(url, body)
fs.readFile(path) · fs.writeFile(path, content)
pool.query(sql, values) · .insert(values) · .eq(column, value)
eval(code)

Narrow candidate families

candidateFamily is assigned only where a request value arriving is inherently dangerous and a rule can express the mitigation:

sink + role	family
http + url	ssrf
exec + command/file/args	command-injection
fs + path	path-traversal
db + sql	sql-injection
eval + code	code-injection

ruleGeneratable: true requires all of: precise evidence · non-null runtimeParameter · a local sink call site · a modelled role · a candidate family.

The refusals matter as much as the acceptances

Each of these is a proven flow — genuine reachability signal — but not a blockable pattern by itself. All are tested explicitly:

fs.writeFileSync("/tmp/x", req.body.contents)   role=content → NOT generatable
db.from(t).insert({ title: req.body.title })    role=values  → NOT generatable
axios.post(url, req.body.payload)               role=body    → NOT generatable
pool.query(sql, [req.body.id])                  role=values  → NOT generatable

That's the over-reach the review warned about by name (path vs contents; generic database values). The reason is reported, not the flow dropped — so it stays useful for reachability while being ineligible for a blocking rule.

Illustrative

The real reference app yields 0 candidates (every flow lands in a db values argument). An Express fixture with the high-risk sinks yields exactly ssrf + path-traversal + command-injection. A generatable candidate carries everything a compiler needs: route + method, runtimeParameter, sink package, evidence span, and the endpoint fingerprint for staleness.

811 tests green; typecheck clean.

Still ahead (Track 2)

The finer confidence taxonomy (exact/transformed/interprocedural), the candidate lifecycle (dry-run → observe → promote → retire on map drift), and corpus metrics — plan §10.

[coderbuds]

Comprehensive adapter summaries integrate argument roles into dataflow analysis.

🎯 Quality: 82% Excellent · 📦 Size: Extra Large — strongly consider breaking this down

🛡️ Standards: no pre-flight fit check ran for this change — wire assess-change-fit into your coding agents to catch size before opening.

📈 This month: Your 57th PR — above team average · Averaging Good

_{See how your team is trending →}

[patchstackdave]

/review