020 — Rust Result 與 #[must_use]：取值被強制，丟棄沒有

{
  "name": "020-rust-must-use",
  "upstream": "Rust: Result, #[must_use], and the unused_must_use lint, measured by running rustc",
  "what_is_being_examined": "Five ways a caller can meet a Result, and which of them the compiler refuses.",

  "the_finding": "Extraction is forced and discarding is not. Using the T without naming the Err case is a type error (E0308), so no lint setting is needed. Dropping the whole value is a warning, and discarding it explicitly with `let _ =` is not even that — it compiles clean under deny(unused_must_use), which is the loudest setting the language offers.",

  "why_it_belongs_beside_example_020": "Example 020 argues that a unit should declare its CAPACITY rather than its state, because a capacity claim is testable. Rust's type system is that argument made structural: Result<T, E> is a declared capacity to be wrong, and the compiler enforces it exactly where the value is used. What it does not do is stop a consumer from refusing to look — which is 改良點 16 appearing inside a type system, since the strength of the remaining signal is the consumer's lint setting.",

  "the_control": "`match { Ok, Err }` — handling written out, compiles clean, no warning. Without it, `let _ = ...` compiling clean would be consistent with every route compiling clean and would be evidence of nothing.",

  "routes": {
    "bare call":         {"claims_compiler_forces_handling": false, "measured": "compiles, must-use warning"},
    "let _ = ...":       {"claims_compiler_forces_handling": false, "measured": "compiles, no warning, and still compiles under deny"},
    ".unwrap_or(0)":     {"claims_compiler_forces_handling": false, "measured": "compiles clean - Err named by method call"},
    "let v: i32 = ...":  {"claims_compiler_forces_handling": true,  "measured": "does NOT compile, E0308"},
    "match { Ok, Err }": {"claims_compiler_forces_handling": false, "measured": "the control - compiles clean"}
  },

  "the_instrument_was_wrong_first": "One defect, fixed, and covered by section 2 of the island test: cargo writes diagnostics to stderr and exits 0, so reading only the return value of execFileSync reported 'no warning' for every route that compiled. I also wrote down a SECOND cause - that a shared package name under a shared target directory would let a cached unit answer silently - and it is not real. The mutation reinstating it stayed green, and measuring it directly showed why: a no-op `Finished` build replays the cached diagnostics. Section 2 measures that instead. It is the first time in this run that a green mutation refuted a defect I had claimed rather than confirming one.",

  "sets": {
    "FMS": "this file: what each route claims and what was measured, the instrument's own failure modes, and the units map",
    "SCL": "the deployment's lint setting, and what that setting cannot reach",
    "SMS": "the compiler probes - each row is a cargo build that really ran",
    "TMS": "one file per route - each carries its snippet and what it claims about the compiler, and imports nothing",
    "DMS": "compiles and the warning column printed together, never one alone"
  },

  "units": {"TMS/routes": ["bare_call.mjs", "direct_assign.mjs", "explicit_discard.mjs", "match_arm.mjs", "unwrap.mjs"]},

  "non_goals": [
    "Establishing anything about type systems in general. This is one type, in one language, on one toolchain - rustc 1.96 - and the claim is demonstrated there rather than proved.",
    "Judging whether let _ = should be reachable by a lint. Clippy has opinions and teams have review; this measures what the compiler does, not what a project can arrange around it.",
    "Comparing with checked exceptions, Option, or Either. Each would need new probes rather than a re-reading of these."
  ]
}

{
  "deployment": "release-pipeline",
  "lint_setting": "deny(unused_must_use)",
  "an_explicitly_discarded_result_is": "not reachable by any lint setting",
  "why": "This pipeline turns the must-use warning into an error, which is the strongest setting the language offers. It is written down here because the measurement shows what that setting does NOT cover, and a policy that implies coverage it does not have is worse than one that names its gap.",
  "what_this_cannot_reach": "let _ = fallible(). It compiles clean under deny(unused_must_use) - the loudest available setting does not stop the explicit discard.",
  "not_a_general_rule": "A codebase where let _ is banned by review, or by a clippy lint the team enables, closes it socially rather than mechanically. SCL is where the position lives."
}

// Probes that run the real compiler. Nothing here is simulated — every row in
// the report is a `cargo build` that actually happened.
//
// One thing about the instrument got it wrong the first time and is worth
// keeping in the source: cargo writes diagnostics to STDERR and exits 0 on a
// warning, and the return value of execFileSync is stdout only — so the first
// version of this file reported "no warning" for every route that compiled.
// spawnSync hands back both streams whatever the exit status.
//
// I also wrote down a second cause — that a shared package name under a shared
// target directory would let a cached unit answer silently — and it is NOT
// real. A mutation reinstating it stayed green, and measuring it directly
// showed why: a no-op `Finished` build REPLAYS the cached diagnostics. Section
// 2 of the island test measures that rather than asserting it. Each probe still
// gets its own package name, which costs nothing and keeps the probes
// independent of that behaviour either way.
import { spawnSync } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";

const ROOT = fs.mkdtempSync(path.join(os.tmpdir(), "mssp-020-"));
const SHARED_TARGET = path.join(ROOT, "target");
let crateCounter = 0;

export const PRELUDE = 'fn fallible() -> Result<i32, String> { Err("broke".into()) }';

export function versions() {
  const rustc = spawnSync("rustc", ["--version"], { encoding: "utf8" });
  const cargo = spawnSync("cargo", ["--version"], { encoding: "utf8" });
  return `${(rustc.stdout ?? "").trim()} | ${(cargo.stdout ?? "").trim()}`;
}

export function available() {
  const probe = spawnSync("cargo", ["--version"], { encoding: "utf8" });
  return probe.status === 0;
}

// Build one crate and report what the compiler said. `deny` puts the lint
// setting in the CONSUMER's crate, which is where it lives in real code.
export function build(body, { deny = false } = {}) {
  crateCounter += 1;
  const dir = fs.mkdtempSync(path.join(ROOT, "crate-"));
  return buildIn(dir, body, { deny, name: `probe${crateCounter}` });
}

// Split out so the island test can write a crate once and then build it TWICE,
// which is the only way to see what a cached build reports. Writing the source
// again gives it a new mtime and forces a recompile — which is what the first
// version of this probe did, so it never saw a cache hit at all.
export function buildIn(dir, body, { deny = false, name = "probe" } = {}) {
  fs.mkdirSync(path.join(dir, "src"), { recursive: true });
  fs.writeFileSync(path.join(dir, "Cargo.toml"),
    `[package]\nname = "${name}"\nversion = "0.1.0"\nedition = "2021"\n`);
  fs.writeFileSync(path.join(dir, "src", "main.rs"),
    `${deny ? "#![deny(unused_must_use)]\n" : ""}${PRELUDE}\nfn main() {\n${body}\n}\n`);
  return rebuild(dir);
}

// Run cargo against a crate already on disk, touching nothing.
export function rebuild(dir) {
  const result = spawnSync("cargo", ["build", "--target-dir", SHARED_TARGET],
    { cwd: dir, encoding: "utf8" });
  const text = `${result.stdout ?? ""}${result.stderr ?? ""}`;
  return {
    compiles: result.status === 0,
    exitStatus: result.status,
    recompiled: /Compiling/.test(text),
    mustUseWarning: /warning: unused `Result` that must be used/.test(text),
    denied: /error: unused `Result` that must be used/.test(text),
    errorCode: (text.match(/error\[([A-Z0-9]+)\]/) ?? [])[1] ?? null,
  };
}

// The challenge: a route claims whether the compiler FORCES the Err case to be
// named. The compiler answers. This is example 020's shape with rustc as the
// oracle — and, as there, the claim is checked by running it.
export function challenge(route) {
  const plain = build(route.BODY);
  const strict = build(route.BODY, { deny: true });
  const forced = plain.compiles === false && plain.errorCode !== null;
  return {
    route: route.NAME,
    claimed: route.CLAIMS_COMPILER_FORCES_HANDLING,
    plain,
    strict,
    forced,
    passed: forced === route.CLAIMS_COMPILER_FORCES_HANDLING,
  };
}

export function cleanup() {
  fs.rmSync(ROOT, { recursive: true, force: true });
}

// Call it and let the Result fall on the floor.
export const NAME = "bare call";
export const BODY = "    fallible();";
export const CLAIMS_COMPILER_FORCES_HANDLING = false;
export const HOW = "the value is dropped; #[must_use] makes it noisy, not impossible";

// Try to use the T without acknowledging the E at all.
export const NAME = "let v: i32 = ...";
export const BODY = "    let v: i32 = fallible();\n    println!(\"{}\", v);";
export const CLAIMS_COMPILER_FORCES_HANDLING = true;
export const HOW = "Result<i32, String> is not i32, so extraction cannot be written without saying something about Err";

// Discard it on purpose. This is the row the entry exists for.
export const NAME = "let _ = ...";
export const BODY = "    let _ = fallible();";
export const CLAIMS_COMPILER_FORCES_HANDLING = false;
export const HOW = "binding to _ is the documented way to say 'I meant to ignore this'";

// The control. It names the Err arm and compiles clean with no warning.
//
// Without it, "let _ = ... compiles clean" would not be evidence of anything:
// it would be consistent with every route compiling clean.
export const NAME = "match { Ok, Err }";
export const BODY = "    let v = match fallible() { Ok(x) => x, Err(_) => 0 };\n    println!(\"{}\", v);";
export const CLAIMS_COMPILER_FORCES_HANDLING = false;
export const HOW = "the control - handling is written out, so nothing needs to be forced";

// Take the value and promise there is no error, at run time.
export const NAME = ".unwrap_or(0)";
export const BODY = "    println!(\"{}\", fallible().unwrap_or(0));";
export const CLAIMS_COMPILER_FORCES_HANDLING = false;
export const HOW = "the Err case is named, but by a method call rather than by the type checker";

// What a person is shown.
//
// `compiles` is never printed without the warning column beside it, because
// "it built" is the answer three different situations share here.
const pad = (value, width) => String(value).padEnd(width);

export function table(rows) {
  const lines = ["    route                compiles   must_use warning   error"];
  for (const row of rows) {
    lines.push(`    ${pad(row.route.NAME, 20)} ${pad(row.compiles ? "yes" : "NO", 10)} `
      + `${pad(row.mustUseWarning ? "yes" : row.denied ? "as an ERROR" : "-", 18)} `
      + `${row.errorCode ?? "-"}`);
  }
  return lines.join("\n");
}

export function boundary(discardPlain, discardStrict, assign) {
  return [
    "  the boundary, in two facts:",
    `    extraction is forced      - ${assign.route.NAME} does not compile (${assign.errorCode})`,
    `    discarding is not         - ${discardPlain.route.NAME} compiles, no warning`,
    `    and the loudest setting available does not change that: still `
      + `${discardStrict.compiles ? "compiles" : "refused"}`,
    "",
    "  So the type system forces the Err case to be NAMED wherever the value is used,",
    "  and forces nothing at all where the value is thrown away.",
  ].join("\n");
}

// The island test, run against the real compiler.
//
//   node src/island_test.mjs
//
// Section 2 checks the INSTRUMENT, because this entry's first version read only
// stdout, where cargo writes no diagnostics at all. It also measures the cache
// claim I wrote down beside that one and could not reproduce: a cached build
// replays its warnings, so the hazard I described does not exist.
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";

import * as compiler from "./SMS/compiler.mjs";
import * as bareCall from "./TMS/routes/bare_call.mjs";
import * as directAssign from "./TMS/routes/direct_assign.mjs";
import * as explicitDiscard from "./TMS/routes/explicit_discard.mjs";
import * as matchArm from "./TMS/routes/match_arm.mjs";
import * as unwrap from "./TMS/routes/unwrap.mjs";

const here = path.dirname(fileURLToPath(import.meta.url));
const FMS = JSON.parse(fs.readFileSync(path.join(here, "FMS", "architecture.json"), "utf8"));
const POLICY = JSON.parse(fs.readFileSync(path.join(here, "SCL", "policy.json"), "utf8"));
const ROUTES = [bareCall, explicitDiscard, unwrap, directAssign, matchArm];
const failures = [];
let ran = 0;
const check = (label, ok, detail = "") => {
  ran += 1;
  process.stdout.write(`  ${ok ? "PASS" : "FAIL"}  ${label}${detail ? ` - ${detail}` : ""}\n`);
  if (!ok) failures.push(label);
};
const say = (line = "") => process.stdout.write(`${line}\n`);

if (!compiler.available()) {
  say("\n  REFUSED: no rust toolchain. This entry measures a compiler and will not guess.");
  process.exit(1);
}
say(`\n  ${compiler.versions()}`);

say("\n== 1. each route is an island, and FMS matches the tree");
for (const [unit, declared] of Object.entries(FMS.units)) {
  const dir = path.join(here, ...unit.split("/"));
  const onDisk = fs.readdirSync(dir).filter((n) => n.endsWith(".mjs")).sort();
  check(`${unit}: FMS declares what is on disk`,
    JSON.stringify(onDisk) === JSON.stringify([...declared].sort()),
    `disk ${onDisk.join(", ")} | FMS ${[...declared].sort().join(", ")}`);
  for (const file of onDisk) {
    const body = fs.readFileSync(path.join(dir, file), "utf8");
    check(`${unit}/${file} imports nothing at all`, !/^\s*import\s/m.test(body));
  }
}
check("every route states what it claims about the compiler",
  ROUTES.every((r) => typeof r.CLAIMS_COMPILER_FORCES_HANDLING === "boolean"));

say("\n== 2. the instrument, checked before anything is measured with it");
const first = compiler.build(bareCall.BODY);
check("a route known to warn does report the warning", first.mustUseWarning === true,
  "cargo writes diagnostics to stderr and exits 0 - reading only stdout loses every one");
check("and it did exit 0 while doing so", first.exitStatus === 0);
// Measured rather than assumed. I first wrote down a second instrument defect -
// that a cached unit would answer silently - and a mutation reinstating it
// stayed GREEN. This is what is actually true, and it is why that hazard does
// not exist here.
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mssp-020-cache-"));
const fresh = compiler.buildIn(dir, bareCall.BODY, { name: "cacheprobe" });
const cached = compiler.rebuild(dir);   // same crate, source untouched
check("building the same directory twice really does hit the cache the second time",
  fresh.recompiled === true && cached.recompiled === false,
  `first ${fresh.recompiled ? "Compiling" : "Finished"}, second ${cached.recompiled ? "Compiling" : "Finished"}`);
check("and the cached build REPLAYS the warning rather than going quiet",
  cached.mustUseWarning === true,
  "so a shared package name is not a hazard here - the claim I first wrote down was wrong");
fs.rmSync(dir, { recursive: true, force: true });
check("a route known NOT to warn reports no warning",
  compiler.build(matchArm.BODY).mustUseWarning === false);
check("so the warning column can take both values", first.mustUseWarning !== compiler.build(matchArm.BODY).mustUseWarning);
const broken = compiler.build("    this is not rust;");
check("and a build that cannot compile is reported as such", broken.compiles === false);

say("\n== 3. the control - handling written out compiles clean");
const control = compiler.build(matchArm.BODY);
check("match names the Err arm and compiles", control.compiles === true);
check("with no must-use warning", control.mustUseWarning === false);
check("and no error code", control.errorCode === null);
const discard = compiler.build(explicitDiscard.BODY);
check("let _ = ... also compiles clean with no warning",
  discard.compiles === true && discard.mustUseWarning === false);
check("so 'compiles clean' is reached by handling AND by discarding",
  control.compiles === discard.compiles && control.mustUseWarning === discard.mustUseWarning,
  "which is why the control has to be here - without it, clean would be evidence of nothing");

say("\n== 4. extraction is forced, discarding is not");
const assign = compiler.build(directAssign.BODY);
check("using the T without naming Err does not compile", assign.compiles === false);
check("and the error is a type error, not a lint", assign.errorCode === "E0308", assign.errorCode ?? "-");
check("while dropping the whole value compiles", compiler.build(bareCall.BODY).compiles === true);
check("and discarding it explicitly compiles without even a warning",
  discard.compiles === true && discard.mustUseWarning === false);
const unwrapped = compiler.build(unwrap.BODY);
check("unwrap_or names Err by method call and compiles clean",
  unwrapped.compiles === true && unwrapped.mustUseWarning === false);

say("\n== 5. and the loudest setting the consumer has does not close it");
const denyBare = compiler.build(bareCall.BODY, { deny: true });
const denyDiscard = compiler.build(explicitDiscard.BODY, { deny: true });
check("deny(unused_must_use) turns the bare call into an error", denyBare.compiles === false);
check("and it names the lint, not a type", denyBare.denied === true && denyBare.errorCode === null);
check("but let _ = ... still compiles under the same setting", denyDiscard.compiles === true);
check("with nothing said about it at all",
  denyDiscard.mustUseWarning === false && denyDiscard.denied === false);
check("so the setting moves one row and not the other",
  denyBare.compiles !== compiler.build(bareCall.BODY).compiles
  && denyDiscard.compiles === discard.compiles);
check("which puts the decision back on the consumer - 改良點 16, inside a type system",
  POLICY.lint_setting === "deny(unused_must_use)");

say("\n== 6. the challenge - each route's claim against the compiler");
for (const route of ROUTES) {
  const result = compiler.challenge(route);
  check(`${route.NAME}: claims forced=${result.claimed}, compiler says ${result.forced}`,
    result.passed === true);
}
const liar = { NAME: "drill-liar", BODY: explicitDiscard.BODY, CLAIMS_COMPILER_FORCES_HANDLING: true };
const drilled = compiler.challenge(liar);
check("DRILL: a route claiming the compiler forces it, when it does not, is caught",
  drilled.passed === false);

say("\n== 7. what this does not settle");
check("#[must_use] is doing real work - the bare call is the one row that moves",
  first.mustUseWarning === true && discard.mustUseWarning === false);
check("SCL names the gap rather than implying coverage",
  POLICY.what_this_cannot_reach.includes("let _ = fallible()"));
check("and this entry measures one type in one language on one toolchain",
  FMS.non_goals.some((g) => /one toolchain|single language|other languages/i.test(g)),
  "the claim is demonstrated on rustc 1.96, not established for type systems in general");

compiler.cleanup();
say("");
if (failures.length > 0) {
  say(`  ${failures.length} FAILED: ${failures.join(" | ")}`);
  process.exitCode = 1;
} else {
  say(`  ${ran} checks passed - every row is a cargo build that really ran`);
}

// Five ways to meet a Result, and what the compiler does about each.
//
//   node src/main.mjs            the table, built by really running cargo
//   node src/main.mjs --strict   exit 1 if this deployment's lint setting has a gap
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

import * as report from "./DMS/report.mjs";
import * as compiler from "./SMS/compiler.mjs";
import * as bareCall from "./TMS/routes/bare_call.mjs";
import * as directAssign from "./TMS/routes/direct_assign.mjs";
import * as explicitDiscard from "./TMS/routes/explicit_discard.mjs";
import * as matchArm from "./TMS/routes/match_arm.mjs";
import * as unwrap from "./TMS/routes/unwrap.mjs";

const here = path.dirname(fileURLToPath(import.meta.url));
const POLICY = JSON.parse(fs.readFileSync(path.join(here, "SCL", "policy.json"), "utf8"));
export const ROUTES = [bareCall, explicitDiscard, unwrap, directAssign, matchArm];
const say = (line = "") => process.stdout.write(`${line}\n`);

function main(argv) {
  if (!compiler.available()) {
    say("\n  REFUSED: no rust toolchain on this machine. This entry measures a compiler and");
    say("  cannot be simulated - it reports nothing rather than reporting a guess.");
    return 1;
  }
  say(`\n  ${compiler.versions()}`);
  say(`  ${POLICY.deployment}: ${POLICY.lint_setting}\n`);

  const rows = ROUTES.map((route) => ({ route, ...compiler.build(route.BODY) }));
  say(report.table(rows));
  say("");
  say("  The control is the last row: handling written out, compiles clean, no warning.");
  say("  Without it, `let _ = ...` compiling clean would be consistent with everything");
  say("  compiling clean, and would be evidence of nothing.\n");

  const strict = ROUTES.map((route) => ({ route, ...compiler.build(route.BODY, { deny: true }) }));
  say(`  and with the consumer's own ${POLICY.lint_setting}:`);
  say(report.table(strict));
  say("");

  const discardPlain = rows.find((r) => r.route === explicitDiscard);
  const discardStrict = strict.find((r) => r.route === explicitDiscard);
  const assignRow = rows.find((r) => r.route === directAssign);
  say(report.boundary(discardPlain, discardStrict, assignRow));

  const gap = discardStrict.compiles === true;
  if (argv.includes("--strict") && gap) {
    say(`\n  --strict: ${POLICY.what_this_cannot_reach}`);
    compiler.cleanup();
    return 1;
  }
  compiler.cleanup();
  return 0;
}

process.exitCode = main(process.argv.slice(2));