asmdiff 0.1.3__tar.gz → 0.1.4__tar.gz

asmdiff-0.1.4/FIELD-TEST-REPORT.md

@@ -0,0 +1,123 @@
+# asmdiff field-test report
+
+**Version tested:** working tree at 0.1.3 (post response-file/object-label/walk-up/verbose fixes), run via `uvx --from <repo>` so the packaged entry point, not the checkout, is what executed.
+**Environment:** S3-Amysynth - a real ESP32-S3 / ESP-IDF v6 firmware (FreeRTOS, TinyUSB, vendored AMY synth engine), `build/compile_commands.json` with 1024 entries, xtensa-esp-elf-gcc 15.2.0 (picolibc via specs in a `@response` file), plus host gcc/clang and g++ for contrast.
+
+## Scenario matrix
+
+| # | Scenario | Result |
+|---|----------|--------|
+| A1 | Small harness, `old_*`/`new_*` auto-pairing, default gcc+clang fallback | works - both pairs found, fold-vs-libcall visible immediately |
+| A2 | Same harness through a config target: glob `cc`, `compile_commands = true`, harness not in db | works - glob resolution announced, soft-miss note printed, xtensa FPU asm side-by-side |
+| A3 | Two-target matrix (`--target s3 --target s3-size`) | works - O2 vs Os counts differ as expected |
+| B1 | Whole-file summary of a real DSP file (`oscillators.c`, 58 functions) via db flags | works - and immediately useful: softfloat `__muldf3`/`__extendsfdf2` calls stand out in oscillator init paths |
+| B2 | `--pair render_lut:render_lut_fb` inside a real file | works |
+| C1 | `--across render_lut` between two config profiles | works - zero-overhead loop spans (`.L*_LEND`) detected on both sides |
+| C2 | `--across` real file vs modified copy outside the tree | fails cleanly: soft-miss note + trimmed "amy.h: No such file" error, `--verbose` hint |
+| C2b | `--across` real file vs copy **next to** the original | **compiles but silently misleads** - see Trap 1 |
+| C3 | Two real files (both in db), per-file summary blocks | works - each file gets its own recorded flags |
+| E1-E3 | Error paths: bogus target, string `flags`, explicit db + absent source | all produce specific, actionable messages (bogus target lists available targets) |
+| E4 | C++ file via `g++` | compiles, functions extracted - but see Trap 3 |
+| F1 | Giant function (`play_delta`, ~1000 insns) across O2/Os | works; see note on span semantics |
+| F2 | Bare `--` extra flags (README's own example) | works |
+| F3 | Source with no functions | `(no functions found)`, no crash |
+| F4 | `--pair` with two files | correct argparse guard pointing at `--across` |
+
+## Traps and gaps (ranked)
+
+### 1. Same-directory copy: identical source, different assembly, one stderr note
+The natural before/after move - copy `oscillators.c` to `osc_tweak.c` in the same
+directory and `--across` them - *succeeds*, because quote-includes resolve next to
+the source. But the copy has no db entry, so it compiles without the recorded
+`-D`/`-I` set: in this project that means no `ESP_PLATFORM`, a different
+`AMY_SAMPLE_RATE`, the portable code paths. The two columns show different
+register allocation and frame sizes **for byte-identical code**. The only
+warning is the one-line soft-miss note, whose implication ("the flag sets now
+differ") is easy to miss. A user would read real codegen differences into a
+header-config artifact.
+
+**Recommendation:** when the two sides of an `--across`/two-file run received
+*different* borrowed-flag sets (one hit, one soft miss), say so loudly - e.g.
+tag the column header `[no db entry]` and print a warning that the comparison
+crosses header configurations.
+
+### 2. Before/after on a project source has no supported path
+The tool's pitch ("what does the compiler emit before and after my rewrite")
+cannot currently be executed for a source that needs db flags, except by
+editing in place and diffing two separate runs by eye, or by maintaining two
+built checkouts with two databases. C2/C2b are both dead ends by design.
+
+**Recommendation (feature):** an opt-in fallback such as "borrow flags from
+the same-basename entry" (with a warning), or an explicit
+`--compile-commands-entry PATH` to name which db entry a given source should
+borrow from. Either would make the copy workflow first-class and would also
+neutralize Trap 1.
+
+### 3. C++ defeats auto-pairing silently
+`_Z9old_scalef` does not start with `old_`, so a C++ harness falls back to
+whole-file summary with no hint about why. Workable via `extern "C"` or
+explicit `--pair` with mangled names, but nothing tells the user that.
+Acceptable for a C-focused tool; a doc note (or a "mangled names detected,
+auto-pairing skipped" hint) would close it.
+
+### 4. Loop spans are coarse on large control flow
+`play_delta` (1001 insns) reports spans like `.L513:676` - two-thirds of the
+function - because any backward branch defines a span, and big switch/dispatch
+functions branch backwards for control flow that is not a loop. The README's
+"the listing and your source know, not the tool" caveat covers this honestly,
+but on 1000-instruction functions the span column stops being informative.
+
+### Minor observations
+- The glob-resolution notice (`cc pattern matched 2 toolchains ...`) prints on
+  every run; correct behavior (never silent), slightly noisy in scripted use.
+- Two-file summary blocks are rendered as independent tables, so their columns
+  do not align with each other - cosmetic.
+- `-ffast-math` after `--` reached the compiler as documented (no behavior
+  change for the test case, which was already folded).
+
+## What clearly works now (regression-verified this session)
+- ESP-IDF v6 out of the box: `@response-file` expansion delivers
+  `-specs=picolibc.specs`; `main.c` and every AMY source compiled with only
+  `-O2 -mlongcalls` supplied by the user.
+- Function extraction is clean: 72/72 real functions on `amy.c`, zero data
+  labels, counts match `.type @function` ground truth.
+- Walk-up discovery: project root, `main/`, and `components/amy/src/` all find
+  `build/compile_commands.json`; the `.git` boundary prevents escaping the repo.
+- Failure UX: 4-line trimmed error with a `--verbose` escape hatch instead of a
+  13 KB flag dump.
+- Config system end-to-end: CWD discovery, `default`, multi-target matrices,
+  glob `cc`, env expansion, precise config error messages.
+
+## Postscript: guards added after this report
+
+Traps 1-3 were addressed in the working tree the same day, and re-verified
+against the scenarios above:
+
+- **Trap 1:** a two-file comparison with borrowed flags on only one side now
+  tags the column `[no db entry]` and warns that differences may be header
+  configuration, not codegen. The C2b rerun makes the case vividly: identical
+  source showed 51 vs 14 instructions (partial outlining under the portable
+  header config) — now labeled instead of silent.
+- **Trap 2:** new `--flags-like PATH` lets a db-less source borrow a named
+  entry's flags. Rerunning C2 and C2b with it produced identical 51/51
+  columns for identical source, in-tree and out-of-tree. The absent-source
+  error and the soft-miss note both suggest the flag when a same-basename
+  entry exists.
+- **Trap 3:** falling back to summary when only mangled `_Z*old_*` symbols
+  exist now prints a note naming `extern "C"` and `--pair` as the outs.
+
+Trap 4 (span coarseness on giant control flow) is documented behavior and
+was left as-is.
+
+## Evaluation
+For its stated job - harness-based codegen comparison and whole-file/function
+inspection of real embedded sources - the tool now works credibly in a real
+ESP-IDF v6 project, with fast (<2 s) turnarounds and output that surfaced a
+genuine finding within minutes (software-double promotion in AMY filter/
+oscillator setup paths via `__extendsfdf2`/`__muldf3` in the calls column).
+Error paths are uniformly specific and short. The remaining weaknesses cluster
+around one theme: comparing *modified copies* of db-backed sources, where the
+current behavior ranges from a clean failure (C2) to a quietly misleading
+success (C2b). That workflow is close enough to the tool's core promise that
+Trap 1's warning and Trap 2's fallback are the highest-value next changes;
+everything else found is polish.

{asmdiff-0.1.3 → asmdiff-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asmdiff
-Version: 0.1.3
+Version: 0.1.4
 Summary: Compare per-function assembly between paired C implementations
 Project-URL: Homepage, https://github.com/rt-rtos/asmdiff
 Project-URL: Repository, https://github.com/rt-rtos/asmdiff
@@ -94,7 +94,8 @@ $ asmdiff.py asmdiff_example.c
 ```
 asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
            [--cc 'CC FLAGS']... [--target NAME]... [--config PATH]
-           [--compile-commands [PATH]] [-v] [-- EXTRA_FLAGS...]
+           [--compile-commands [PATH]] [--flags-like PATH] [-v]
+           [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -106,6 +107,7 @@ asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
 | `--target NAME` | A named target from the config file, resolved to a `--cc` entry. Repeatable; appended to the matrix after `--cc` entries. |
 | `--config PATH` | Config file to use. Default search: `asmdiff.toml` next to `SOURCE.c`, then in the current directory, then `~/.config/`. First hit wins. |
 | `--compile-commands [PATH]` | Borrow each source's include/define flags from a `compile_commands.json`; with no `PATH`, walk up from the CWD checking each directory and its `build/` until the repository root. See [below](#borrowing-includes-from-compile_commandsjson). |
+| `--flags-like PATH` | A source with no `compile_commands` entry borrows the flags recorded for `PATH` — the way to compare a modified copy of a project source under its original's header environment. |
 | `-v`, `--verbose` | On compile failure, print the full compiler command and complete error output. Default shows only the compiler, the source, and the first error lines. |
 | `-- FLAGS...` | Everything after a bare `--` is appended to *every* compiler invocation. |
 
@@ -275,6 +277,29 @@ instead of being an error. That keeps standalone harness files working
 when a `build/` directory happens to sit nearby; an explicitly named
 database still treats an absent source as the error it is.
 
+If a two-file comparison ends up with borrowed flags on only *one* side,
+the mismatched column is tagged `[no db entry]` and a warning is printed:
+the two sides then differ in header configuration — defines, include
+paths — not just source, and byte-identical code can compile to visibly
+different assembly. Don't read codegen meaning into such a diff.
+
+### Comparing a modified copy of a project source
+
+The before/after workflow — copy `oscillators.c` to `osc_tweak.c`, change
+one thing, `--across` them — is exactly the situation above: the copy has
+no database entry. `--flags-like` names the entry the copy should borrow:
+
+```bash
+asmdiff.py src/oscillators.c src/osc_tweak.c --across render_lut \
+           --target s3 --flags-like src/oscillators.c
+```
+
+Both sides now compile under the same recorded header environment, so the
+diff is your edit and nothing else. This also covers a git-worktree
+baseline (`../baseline/src/oscillators.c`), which is the same file under a
+path the database has never heard of. The absent-source error and the
+soft-miss note both point at this flag when a same-name entry exists.
+
 ## Whole-file summary
 
 With no `--pair`, no `--across`, and no `old_*`/`new_*` functions to

{asmdiff-0.1.3 → asmdiff-0.1.4}/README.md

@@ -76,7 +76,8 @@ $ asmdiff.py asmdiff_example.c
 ```
 asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
            [--cc 'CC FLAGS']... [--target NAME]... [--config PATH]
-           [--compile-commands [PATH]] [-v] [-- EXTRA_FLAGS...]
+           [--compile-commands [PATH]] [--flags-like PATH] [-v]
+           [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -88,6 +89,7 @@ asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
 | `--target NAME` | A named target from the config file, resolved to a `--cc` entry. Repeatable; appended to the matrix after `--cc` entries. |
 | `--config PATH` | Config file to use. Default search: `asmdiff.toml` next to `SOURCE.c`, then in the current directory, then `~/.config/`. First hit wins. |
 | `--compile-commands [PATH]` | Borrow each source's include/define flags from a `compile_commands.json`; with no `PATH`, walk up from the CWD checking each directory and its `build/` until the repository root. See [below](#borrowing-includes-from-compile_commandsjson). |
+| `--flags-like PATH` | A source with no `compile_commands` entry borrows the flags recorded for `PATH` — the way to compare a modified copy of a project source under its original's header environment. |
 | `-v`, `--verbose` | On compile failure, print the full compiler command and complete error output. Default shows only the compiler, the source, and the first error lines. |
 | `-- FLAGS...` | Everything after a bare `--` is appended to *every* compiler invocation. |
 
@@ -257,6 +259,29 @@ instead of being an error. That keeps standalone harness files working
 when a `build/` directory happens to sit nearby; an explicitly named
 database still treats an absent source as the error it is.
 
+If a two-file comparison ends up with borrowed flags on only *one* side,
+the mismatched column is tagged `[no db entry]` and a warning is printed:
+the two sides then differ in header configuration — defines, include
+paths — not just source, and byte-identical code can compile to visibly
+different assembly. Don't read codegen meaning into such a diff.
+
+### Comparing a modified copy of a project source
+
+The before/after workflow — copy `oscillators.c` to `osc_tweak.c`, change
+one thing, `--across` them — is exactly the situation above: the copy has
+no database entry. `--flags-like` names the entry the copy should borrow:
+
+```bash
+asmdiff.py src/oscillators.c src/osc_tweak.c --across render_lut \
+           --target s3 --flags-like src/oscillators.c
+```
+
+Both sides now compile under the same recorded header environment, so the
+diff is your edit and nothing else. This also covers a git-worktree
+baseline (`../baseline/src/oscillators.c`), which is the same file under a
+path the database has never heard of. The absent-source error and the
+soft-miss note both point at this flag when a same-name entry exists.
+
 ## Whole-file summary
 
 With no `--pair`, no `--across`, and no `old_*`/`new_*` functions to

{asmdiff-0.1.3 → asmdiff-0.1.4}/asmdiff.py

@@ -12,7 +12,8 @@ Usage:
     tools/asmdiff/asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]...
                              [--across FUNC]... [--cc 'CC FLAGS']...
                              [--target NAME]... [--config PATH]
-                             [--compile-commands [PATH]] [-v]
+                             [--compile-commands [PATH]]
+                             [--flags-like PATH] [-v]
                              [-- EXTRA_FLAGS...]
 
 Three modes:
@@ -38,7 +39,9 @@ compile_commands = true in a target — or a bare --compile-commands on the
 command line — instead finds the database by checking each directory from
 the CWD up to the repository root, and its build/ subdirectory; a source
 absent from a database found that way is compiled without borrowed flags
-(with a note) rather than being an error.
+(with a note) rather than being an error.  --flags-like PATH lets such a
+source borrow the flags recorded for PATH, so a modified copy compares
+against its original under one header environment.
 """
 import argparse
 import glob
@@ -81,6 +84,12 @@ _CC_DB_PLAIN_FLAGS = ("-D", "-U")
 _CC_DB_EQ_FLAGS = ("-specs", "--specs", "--sysroot")
 _DB_CACHE = {}
 _MISS_NOTED = set()
+_BORROW_NOTED = set()
+# --flags-like PATH: a source with no database entry borrows the flags
+# recorded for PATH.  This is how a modified copy of a project source gets
+# the same header environment as its original, so an --across between them
+# compares codegen instead of header configurations.
+FLAGS_LIKE = None
 
 
 class Target(str):
@@ -257,9 +266,47 @@ def compile_commands_flags(db_path, source, missing_ok=False):
     and the message flags a same-name entry recorded under a different path.
     With ``missing_ok`` (auto-discovered databases) an absent source instead
     compiles without borrowed flags, after a one-time note per (db, source).
+    In either mode, --flags-like PATH satisfies an absent source with the
+    flags recorded for PATH — the modified-copy workflow.
     """
     entries = load_compile_commands(db_path)
     want = Path(source).resolve()
+    flags, name_seen = _lookup_entry(entries, want)
+    if flags is not None:
+        return flags
+    if FLAGS_LIKE:
+        like = Path(FLAGS_LIKE).resolve()
+        like_flags, _ = _lookup_entry(entries, like)
+        if like_flags is None:
+            sys.exit(f"error: --flags-like {FLAGS_LIKE} "
+                     f"not found in {db_path}")
+        key = (db_path, str(want))
+        if key not in _BORROW_NOTED:
+            _BORROW_NOTED.add(key)
+            print(f"note: {source} not in {db_path}; borrowing the flags "
+                  f"recorded for {FLAGS_LIKE}", file=sys.stderr)
+        return like_flags
+    suggest = ("; --flags-like PATH can borrow another entry's flags"
+               if name_seen else "")
+    if missing_ok:
+        key = (db_path, str(want))
+        if key not in _MISS_NOTED:
+            _MISS_NOTED.add(key)
+            print(f"note: {source} not in {db_path}; compiling without "
+                  f"its include/define flags{suggest}", file=sys.stderr)
+        return []
+    hint = (f"; an entry named {want.name} exists under a different path — "
+            "pass the source as it appears in the database, or borrow its "
+            "flags with --flags-like") if name_seen else ""
+    sys.exit(f"error: {source} not found in {db_path}{hint}")
+
+
+def _lookup_entry(entries, want):
+    """Flags for the entry whose file resolves to ``want``, or None.
+
+    The second result reports whether some entry shares ``want``'s
+    basename — the raw material for the miss hints above.
+    """
     name_seen = False
     for entry in entries:
         f = entry.get("file")
@@ -278,20 +325,10 @@ def compile_commands_flags(db_path, source, missing_ok=False):
             tokens = (list(args) if isinstance(args, list)
                       else shlex.split(entry.get("command", "")))
             tokens = _expand_response_files(tokens, directory)
-            return include_flags(tokens, directory)
+            return include_flags(tokens, directory), name_seen
         if Path(f).name == want.name:
             name_seen = True
-    if missing_ok:
-        key = (db_path, str(want))
-        if key not in _MISS_NOTED:
-            _MISS_NOTED.add(key)
-            print(f"note: {source} not in {db_path}; "
-                  "compiling without its include/define flags",
-                  file=sys.stderr)
-        return []
-    hint = (f"; an entry named {want.name} exists under a different path — "
-            "pass the source as it appears in the database") if name_seen else ""
-    sys.exit(f"error: {source} not found in {db_path}{hint}")
+    return None, name_seen
 
 # A label at column 0 that is not a local (.L*) label starts a function.
 FUNC_LABEL = re.compile(r"^([A-Za-z_][\w$.]*):")
@@ -640,6 +677,41 @@ def compile_to_asm(cc_cmd, extra_flags, harness, out_dir):
     return out_s.read_text()
 
 
+def mark_db_misses(cc_cmd, sources, tags):
+    """Column tags for a two-file comparison, marking a side that compiled
+    without borrowed flags while the other side had them.
+
+    That situation — one source in the database, its copy not — means the
+    columns differ in header configuration (defines, include paths), not
+    just in source, so byte-identical code can show different assembly.
+    The marked tag and a warning keep that from reading as a codegen
+    finding.  Both sides missing is a consistent environment: no warning.
+    """
+    db = getattr(cc_cmd, "compile_commands", None)
+    if not db:
+        return list(tags)
+    missed = [(db, str(Path(s).resolve())) in _MISS_NOTED for s in sources]
+    if not any(missed) or all(missed):
+        return list(tags)
+    print("warning: only one side got flags from the database — assembly "
+          "differences may reflect header configuration, not source "
+          "changes; --flags-like PATH gives the copy its original's flags",
+          file=sys.stderr)
+    return [t + " [no db entry]" if m else t for t, m in zip(tags, missed)]
+
+
+# C++ mangles old_scale(float) to _Z9old_scalef: the old_/new_ prefixes
+# survive inside the mangled name but no longer lead it, so auto-pairing
+# finds nothing and would fall back to the summary without explanation.
+MANGLED_PAIR = re.compile(r"_Z\d+(?:old|new)_")
+
+
+def mangled_pair_hint(names):
+    """True when the extracted names look like C++-mangled old_*/new_*
+    functions — the harness probably just needs extern \"C\"."""
+    return any(MANGLED_PAIR.match(n) for n in names)
+
+
 def side_by_side(left, right, ltitle, rtitle, width=44):
     """Two-column view of a pair's asm lines."""
     rows = [f"{ltitle:<{width}} | {rtitle}",
@@ -762,9 +834,10 @@ def run_across(sources, matrix, fn_names, extra_flags, tmp):
             if len(sides) < 2:
                 continue
             ran_any = True
+            tags = mark_db_misses(cc_cmd, sources,
+                                  file_tags(sources[0], sources[1]))
             print(f"\n== {cc_cmd} ==\n")
-            report_across(fn_names, sides[0], sides[1],
-                          *file_tags(sources[0], sources[1]))
+            report_across(fn_names, sides[0], sides[1], *tags)
         if not ran_any:
             sys.exit("error: no usable compiler in the matrix")
         return 0
@@ -802,8 +875,10 @@ def run_summary(sources, matrix, extra_flags, tmp):
         if len(sections) < len(sources):
             continue
         ran_any = True
+        shown = (mark_db_misses(cc_cmd, sources, tags)
+                 if len(sources) == 2 else tags)
         print(f"\n== {cc_cmd} ==")
-        for tag, funcs in zip(tags, sections):
+        for tag, funcs in zip(shown, sections):
             if len(sections) > 1:
                 print(f"\n-- {tag} --")
             print()
@@ -830,6 +905,10 @@ def run_pairs(source, matrix, pair_specs, extra_flags, tmp):
         pairs = ([tuple(p.split(":", 1)) for p in pair_specs]
                  or auto_pairs(funcs))
         if not pairs:
+            if mangled_pair_hint(funcs):
+                print('note: C++ mangling defeats old_*/new_* auto-pairing; '
+                      'declare the pairs extern "C" or use --pair with the '
+                      'mangled names', file=sys.stderr)
             print(f"\n== {cc_cmd} ==\n")
             print(file_summary_table(funcs) if funcs
                   else "(no functions found)")
@@ -893,13 +972,20 @@ def main(argv=None):
                         help=f"config file; default search: {CONFIG_NAME} "
                              "next to SOURCE.c, in the current directory, "
                              "then in ~/.config/")
+    parser.add_argument("--flags-like", metavar="PATH",
+                        help="when a source has no compile_commands entry, "
+                             "borrow the include/define flags recorded for "
+                             "PATH — lets a modified copy of a project "
+                             "source compile (and compare) under its "
+                             "original's header environment")
     parser.add_argument("-v", "--verbose", action="store_true",
                         help="on compile failure, print the full compiler "
                              "command and complete error output instead of "
                              "the first lines")
     args = parser.parse_args(argv)
-    global VERBOSE
+    global VERBOSE, FLAGS_LIKE
     VERBOSE = args.verbose
+    FLAGS_LIKE = args.flags_like
 
     if len(args.sources) > 2:
         parser.error("at most two source files may be given")

{asmdiff-0.1.3 → asmdiff-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "asmdiff"
-version = "0.1.3"
+version = "0.1.4"
 description = "Compare per-function assembly between paired C implementations"
 readme = "README.md"
 license = "MIT"

{asmdiff-0.1.3 → asmdiff-0.1.4}/test_asmdiff.py

@@ -647,6 +647,115 @@ __func__$1:
         self.assertEqual(insns, 2)
 
 
+class TestFlagsLike(unittest.TestCase):
+    """--flags-like: a source absent from the db borrows a named entry."""
+
+    def _db(self, tmp):
+        path = Path(tmp) / "compile_commands.json"
+        path.write_text(json.dumps([{
+            "directory": tmp, "file": f"{tmp}/real.c",
+            "command": "cc -Iinc -DESP_PLATFORM -c real.c"}]))
+        asmdiff._DB_CACHE.clear()
+        asmdiff._MISS_NOTED.clear()
+        return str(path)
+
+    def test_missing_source_borrows_named_entry(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = self._db(tmp)
+            asmdiff.FLAGS_LIKE = f"{tmp}/real.c"
+            try:
+                err = io.StringIO()
+                with contextlib.redirect_stderr(err):
+                    flags = asmdiff.compile_commands_flags(
+                        db, f"{tmp}/copy.c", missing_ok=True)
+            finally:
+                asmdiff.FLAGS_LIKE = None
+            self.assertEqual(flags, ["-I", f"{tmp}/inc", "-DESP_PLATFORM"])
+            self.assertIn("real.c", err.getvalue())     # borrow is announced
+            # A satisfied borrow is not a miss: no apples-to-oranges state.
+            self.assertEqual(asmdiff._MISS_NOTED, set())
+
+    def test_applies_to_explicit_db_too(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = self._db(tmp)
+            asmdiff.FLAGS_LIKE = f"{tmp}/real.c"
+            try:
+                with contextlib.redirect_stderr(io.StringIO()):
+                    flags = asmdiff.compile_commands_flags(
+                        db, f"{tmp}/copy.c", missing_ok=False)
+            finally:
+                asmdiff.FLAGS_LIKE = None
+            self.assertEqual(flags[-1], "-DESP_PLATFORM")
+
+    def test_bad_flags_like_target_is_an_error(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = self._db(tmp)
+            asmdiff.FLAGS_LIKE = f"{tmp}/nowhere.c"
+            try:
+                with self.assertRaises(SystemExit):
+                    asmdiff.compile_commands_flags(db, f"{tmp}/copy.c",
+                                                   missing_ok=True)
+            finally:
+                asmdiff.FLAGS_LIKE = None
+
+    def test_miss_messages_suggest_flags_like(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            db = self._db(tmp)
+            with self.assertRaises(SystemExit) as ctx:   # hard error path
+                asmdiff.compile_commands_flags(db, f"{tmp}/other/real.c")
+            self.assertIn("--flags-like", str(ctx.exception))
+            err = io.StringIO()                          # soft-miss path
+            with contextlib.redirect_stderr(err):
+                asmdiff.compile_commands_flags(db, f"{tmp}/sub/real.c",
+                                               missing_ok=True)
+            self.assertIn("--flags-like", err.getvalue())
+
+
+class TestMarkDbMisses(unittest.TestCase):
+    """Two-file comparisons where only one side got borrowed flags."""
+
+    def _entry(self, db):
+        return asmdiff.Target("gcc -O2", db, db_discovered=True)
+
+    def test_one_sided_miss_tags_and_warns(self):
+        asmdiff._MISS_NOTED.clear()
+        asmdiff._MISS_NOTED.add(("/db.json", str(Path("b.c").resolve())))
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            tags = asmdiff.mark_db_misses(self._entry("/db.json"),
+                                          ["a.c", "b.c"], ("a.c", "b.c"))
+        self.assertEqual(tags, ["a.c", "b.c [no db entry]"])
+        self.assertIn("header", err.getvalue())
+
+    def test_both_missed_means_same_env_no_warning(self):
+        asmdiff._MISS_NOTED.clear()
+        for s in ("a.c", "b.c"):
+            asmdiff._MISS_NOTED.add(("/db.json", str(Path(s).resolve())))
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            tags = asmdiff.mark_db_misses(self._entry("/db.json"),
+                                          ["a.c", "b.c"], ("a.c", "b.c"))
+        self.assertEqual(tags, ["a.c", "b.c"])
+        self.assertEqual(err.getvalue(), "")
+
+    def test_no_db_entry_untouched(self):
+        tags = asmdiff.mark_db_misses("gcc -O2", ["a.c", "b.c"],
+                                      ("a.c", "b.c"))
+        self.assertEqual(tags, ["a.c", "b.c"])
+
+
+class TestMangledPairHint(unittest.TestCase):
+    def test_mangled_old_new_detected(self):
+        self.assertTrue(asmdiff.mangled_pair_hint(
+            ["_Z9old_scalef", "_Z9new_scalef"]))
+
+    def test_plain_c_names_no_hint(self):
+        self.assertFalse(asmdiff.mangled_pair_hint(["scale", "helper"]))
+
+    def test_mangled_but_not_old_new_no_hint(self):
+        self.assertFalse(asmdiff.mangled_pair_hint(["_Z6renderv"]))
+
+
 class TestCompileFailureOutput(unittest.TestCase):
     CMD = ["xtensa-gcc", "-O2"] + [f"-I/inc{i}" for i in range(50)] + ["a.c"]
     STDERR = "\n".join(f"err line {i}" for i in range(60))