asmdiff 0.1.2__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.2 → asmdiff-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asmdiff
-Version: 0.1.2
+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]] [-- EXTRA_FLAGS...]
+           [--compile-commands [PATH]] [--flags-like PATH] [-v]
+           [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -105,7 +106,9 @@ asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
 | `--cc 'CC FLAGS'` | One compiler invocation, command and flags in a single quoted string. Repeatable to build a matrix. |
 | `--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`, search `./`, `./build`, `../`, `../build`. See [below](#borrowing-includes-from-compile_commandsjson). |
+| `--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. |
 
 With no `--cc` and no `--target`, the config file's top-level
@@ -207,7 +210,8 @@ compile_commands = "$HOME/myproject/build/compile_commands.json"
 Now `asmdiff.py $HOME/myproject/components/dsp/biquad.c --target esp32s3-idf`
 finds that file's entry in the database and adds the include/define flags
 it recorded — `-I`, `-isystem`, `-iquote`, `-idirafter`, `-include`,
-`-imacros`, `-D`, `-U` — to this target's command. Everything else the
+`-imacros`, `-D`, `-U`, plus the header-environment driver flags `-specs`
+and `--sysroot` — to this target's command. Everything else the
 database records (its own compiler, `-O`/`-std`/`-W` flags, `-c`, `-o`, the
 source) is ignored: **you** own the compiler and optimisation flags via
 `cc`/`flags`; only the header environment is borrowed. That split is the
@@ -219,6 +223,12 @@ Details that make it robust:
 - **Paths are made absolute** against each entry's `directory`, so a
   database full of build-relative `-I../include` flags still resolves when
   asmdiff runs from anywhere.
+- **`@file` response files are expanded.** Build systems park flags in
+  them — ESP-IDF v6 hides `-specs=picolibc.specs` in
+  `build/toolchain/cflags`, and without it every libc header breaks —
+  so the flag scan reads them (nested ones too) instead of skipping the
+  token. A bare specs name is left for the compiler's own search
+  directories; a specs path resolves like any other recorded path.
 - **Per source file.** The lookup keys on the source you pass (matched by
   resolved absolute path), so two files in an `--across`/summary run each
   get their own recorded flags.
@@ -246,12 +256,15 @@ asmdiff.py biquad.c --compile-commands            # same, for any matrix
 asmdiff.py biquad.c --compile-commands path/to/compile_commands.json
 ```
 
-Both search `./`, `./build`, `../`, `../build` — first hit wins — which
-covers running from a project root or from one directory below it (a
-component dir), with the database where CMake/idf.py leaves it. Finding
-nothing is an error: discovery is opt-in, so if you asked for it, silence
-would be a lie. It is never on by default — a target without
-`compile_commands` and no `--compile-commands` flag borrows nothing.
+Both walk up from the current directory, checking each level for
+`compile_commands.json` and then `build/compile_commands.json` (where
+CMake and idf.py leave it) — first hit wins. The walk stops at the
+repository root (the first directory with a `.git`), so running from any
+depth of component directory finds the project database, but an unrelated
+one further up the filesystem is never picked up. Finding nothing is an
+error: discovery is opt-in, so if you asked for it, silence would be a
+lie. It is never on by default — a target without `compile_commands` and
+no `--compile-commands` flag borrows nothing.
 
 The precedence is what you'd hope: a target that names its own
 `compile_commands` path always keeps it; `--compile-commands` (with or
@@ -264,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
@@ -292,6 +328,12 @@ weight, did a call appear that shouldn't have? It sums parsed function
 bodies only (no literal pools, data, or alignment), so it is not a size
 measurement, and per-function rows are where the real information is.
 
+Only labels the assembler types as functions are listed — global data
+(string constants, state structs, lookup tables) gets column-0 labels too
+but is not code. A `calls` list longer than 8 symbols is truncated to
+`..., +N more`; real firmware dispatch functions call dozens of distinct
+symbols and would otherwise make rows thousands of characters wide.
+
 ## Comparing the same function across two builds (`--across`)
 
 `--pair` needs both variants to coexist in one compilation. Real changes

{asmdiff-0.1.2 → 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]] [-- EXTRA_FLAGS...]
+           [--compile-commands [PATH]] [--flags-like PATH] [-v]
+           [-- EXTRA_FLAGS...]
 ```
 
 | Option | Meaning |
@@ -87,7 +88,9 @@ asmdiff.py SOURCE.c [SOURCE2.c] [--pair OLD:NEW]... [--across FUNC]...
 | `--cc 'CC FLAGS'` | One compiler invocation, command and flags in a single quoted string. Repeatable to build a matrix. |
 | `--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`, search `./`, `./build`, `../`, `../build`. See [below](#borrowing-includes-from-compile_commandsjson). |
+| `--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. |
 
 With no `--cc` and no `--target`, the config file's top-level
@@ -189,7 +192,8 @@ compile_commands = "$HOME/myproject/build/compile_commands.json"
 Now `asmdiff.py $HOME/myproject/components/dsp/biquad.c --target esp32s3-idf`
 finds that file's entry in the database and adds the include/define flags
 it recorded — `-I`, `-isystem`, `-iquote`, `-idirafter`, `-include`,
-`-imacros`, `-D`, `-U` — to this target's command. Everything else the
+`-imacros`, `-D`, `-U`, plus the header-environment driver flags `-specs`
+and `--sysroot` — to this target's command. Everything else the
 database records (its own compiler, `-O`/`-std`/`-W` flags, `-c`, `-o`, the
 source) is ignored: **you** own the compiler and optimisation flags via
 `cc`/`flags`; only the header environment is borrowed. That split is the
@@ -201,6 +205,12 @@ Details that make it robust:
 - **Paths are made absolute** against each entry's `directory`, so a
   database full of build-relative `-I../include` flags still resolves when
   asmdiff runs from anywhere.
+- **`@file` response files are expanded.** Build systems park flags in
+  them — ESP-IDF v6 hides `-specs=picolibc.specs` in
+  `build/toolchain/cflags`, and without it every libc header breaks —
+  so the flag scan reads them (nested ones too) instead of skipping the
+  token. A bare specs name is left for the compiler's own search
+  directories; a specs path resolves like any other recorded path.
 - **Per source file.** The lookup keys on the source you pass (matched by
   resolved absolute path), so two files in an `--across`/summary run each
   get their own recorded flags.
@@ -228,12 +238,15 @@ asmdiff.py biquad.c --compile-commands            # same, for any matrix
 asmdiff.py biquad.c --compile-commands path/to/compile_commands.json
 ```
 
-Both search `./`, `./build`, `../`, `../build` — first hit wins — which
-covers running from a project root or from one directory below it (a
-component dir), with the database where CMake/idf.py leaves it. Finding
-nothing is an error: discovery is opt-in, so if you asked for it, silence
-would be a lie. It is never on by default — a target without
-`compile_commands` and no `--compile-commands` flag borrows nothing.
+Both walk up from the current directory, checking each level for
+`compile_commands.json` and then `build/compile_commands.json` (where
+CMake and idf.py leave it) — first hit wins. The walk stops at the
+repository root (the first directory with a `.git`), so running from any
+depth of component directory finds the project database, but an unrelated
+one further up the filesystem is never picked up. Finding nothing is an
+error: discovery is opt-in, so if you asked for it, silence would be a
+lie. It is never on by default — a target without `compile_commands` and
+no `--compile-commands` flag borrows nothing.
 
 The precedence is what you'd hope: a target that names its own
 `compile_commands` path always keeps it; `--compile-commands` (with or
@@ -246,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
@@ -274,6 +310,12 @@ weight, did a call appear that shouldn't have? It sums parsed function
 bodies only (no literal pools, data, or alignment), so it is not a size
 measurement, and per-function rows are where the real information is.
 
+Only labels the assembler types as functions are listed — global data
+(string constants, state structs, lookup tables) gets column-0 labels too
+but is not code. A `calls` list longer than 8 symbols is truncated to
+`..., +N more`; real firmware dispatch functions call dozens of distinct
+symbols and would otherwise make rows thousands of characters wide.
+
 ## Comparing the same function across two builds (`--across`)
 
 `--pair` needs both variants to coexist in one compilation. Real changes

{asmdiff-0.1.2 → asmdiff-0.1.4}/asmdiff.example.toml

@@ -42,8 +42,9 @@ flags = ["-O2", "-mlongcalls", "-DNDEBUG"]
 # never transcribe include paths by hand.  The compiler and -O/-m flags
 # still come from cc/flags; only the header environment is borrowed.
 # A path expands ~ and $VARS; `compile_commands = true` instead searches
-# ./, ./build, ../, ../build at run time (a source missing from a database
-# found that way is compiled without borrowed flags, with a note).
+# at run time: each directory from the CWD up to the repository root,
+# and its build/ subdirectory (a source missing from a database found
+# that way is compiled without borrowed flags, with a note).
 [esp32s3-idf]
 cc = "$HOME/.espressif/tools/xtensa-esp-elf/esp-*/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"
 flags = ["-O2", "-mlongcalls"]

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

@@ -13,6 +13,7 @@ Usage:
                              [--across FUNC]... [--cc 'CC FLAGS']...
                              [--target NAME]... [--config PATH]
                              [--compile-commands [PATH]]
+                             [--flags-like PATH] [-v]
                              [-- EXTRA_FLAGS...]
 
 Three modes:
@@ -35,9 +36,12 @@ the include/define flags recorded there for the source being compiled are
 added to that target's command, so a real project source resolves its
 headers the way its own build system does (e.g. an ESP-IDF component).
 compile_commands = true in a target — or a bare --compile-commands on the
-command line — instead searches ./, ./build, ../, ../build for the
-database; a source absent from a database found that way is compiled
-without borrowed flags (with a note) rather than being an error.
+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.  --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
@@ -73,8 +77,19 @@ CONFIG_NAME = "asmdiff.toml"
 _CC_DB_PATH_FLAGS = ("-I", "-iquote", "-isystem", "-idirafter",
                      "-include", "-imacros", "-isysroot")
 _CC_DB_PLAIN_FLAGS = ("-D", "-U")
+# Driver-level flags that also shape the header environment: a specs file
+# can swap the entire libc header set (ESP-IDF v6 selects picolibc via
+# -specs=picolibc.specs), and --sysroot moves every system include.  Both
+# accept =-glued and split spellings; both are re-emitted =-glued.
+_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):
@@ -105,6 +120,43 @@ def _abs_against(directory, value):
     return str(p)
 
 
+def _expand_response_files(tokens, directory, depth=0):
+    """Inline GCC @file response files: each @FILE token is replaced by the
+    shlex-split contents of FILE, resolved against the entry's ``directory``
+    (the CWD the driver ran from).  Build systems park header-environment
+    flags there — ESP-IDF v6 hides -specs=picolibc.specs in one — so
+    skipping them silently loses flags this feature exists to borrow.
+    An unreadable file is warned about and dropped; nesting is bounded as
+    a cycle guard.
+    """
+    out = []
+    for tok in tokens:
+        if not tok.startswith("@") or len(tok) == 1:
+            out.append(tok)
+            continue
+        path = _abs_against(directory, tok[1:])
+        try:
+            content = Path(path).read_text()
+        except OSError:
+            print(f"warning: response file {path} not readable; "
+                  "flags inside it are not borrowed", file=sys.stderr)
+            continue
+        inner = shlex.split(content)
+        if depth < 8:
+            inner = _expand_response_files(inner, directory, depth + 1)
+        out += inner
+    return out
+
+
+def _specs_value(directory, value):
+    """A specs argument with a path separator is a file path (resolved like
+    any other); a bare name (picolibc.specs) is looked up in the compiler's
+    own search directories and must pass through untouched."""
+    if "/" in value or os.sep in value:
+        return _abs_against(directory, value)
+    return value
+
+
 def include_flags(tokens, directory):
     """Pick header-search, forced-include, and define flags out of one
     recorded compile command; make relative paths absolute against
@@ -124,6 +176,19 @@ def include_flags(tokens, directory):
                 flags += [f, _abs_against(directory, tok[len(f):])]
                 matched = True
                 break
+        if not matched:
+            for f in _CC_DB_EQ_FLAGS:
+                value = None
+                if tok == f and i + 1 < n:                # -specs file
+                    value, extra = tokens[i + 1], 1
+                elif tok.startswith(f + "="):             # -specs=file
+                    value = tok[len(f) + 1:]
+                if value is not None:
+                    resolve = (_specs_value if f.endswith("specs")
+                               else _abs_against)
+                    flags.append(f + "=" + resolve(directory, value))
+                    matched = True
+                    break
         if not matched:
             for f in _CC_DB_PLAIN_FLAGS:
                 if tok == f and i + 1 < n:                # -D FOO
@@ -138,18 +203,26 @@ def include_flags(tokens, directory):
 
 
 def find_compile_commands():
-    """Locate a compile_commands.json near the current directory.
-
-    Searched in order: ./, ./build, ../, ../build — first hit wins.  This
-    covers running asmdiff from a project root or from one directory below
-    it (a component dir), with the database where CMake/idf.py leaves it.
-    Returns None when nothing is found.
+    """Locate a compile_commands.json by walking up from the current
+    directory.
+
+    Each directory from the CWD upward is checked for the database itself,
+    then for build/compile_commands.json (where CMake and idf.py leave it),
+    so the search works from a project root or from any depth of component
+    directory.  The walk stops at the first directory containing .git (the
+    repository root — checked after that directory's own candidates) or
+    after a bounded number of levels, so an unrelated database further up
+    the filesystem is never picked up.  Returns None when nothing is found.
     """
-    cwd = Path.cwd()
-    for d in (cwd, cwd / "build", cwd.parent, cwd.parent / "build"):
-        candidate = d / "compile_commands.json"
-        if candidate.is_file():
-            return str(candidate)
+    d = Path.cwd()
+    for _ in range(10):
+        for candidate in (d / "compile_commands.json",
+                          d / "build" / "compile_commands.json"):
+            if candidate.is_file():
+                return str(candidate)
+        if (d / ".git").exists() or d.parent == d:
+            return None
+        d = d.parent
     return None
 
 
@@ -159,8 +232,9 @@ def _discovered_db(who):
     not a silent no-op."""
     found = find_compile_commands()
     if found is None:
-        sys.exit(f"error: {who}: no compile_commands.json found in "
-                 "./, ./build, ../, or ../build")
+        sys.exit(f"error: {who}: no compile_commands.json found in the "
+                 "current directory, its build/, or any parent up to the "
+                 "repository root")
     return found
 
 
@@ -192,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")
@@ -212,27 +324,26 @@ def compile_commands_flags(db_path, source, missing_ok=False):
             args = entry.get("arguments")
             tokens = (list(args) if isinstance(args, list)
                       else shlex.split(entry.get("command", "")))
-            return include_flags(tokens, directory)
+            tokens = _expand_response_files(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$.]*):")
-# Assembler directives that carry no information worth reading.
+# .type NAME, @object|@function — gcc/clang emit this before the label on
+# ELF.  Objects (string constants like __func__, global state, LUTs) get
+# column-0 labels too and must not be reported as functions.  The type
+# marker is @ on x86/Xtensa/RISC-V, % on ARM, # on some targets.
+TYPE_DIRECTIVE = re.compile(r'^\s*\.type\s+([^,\s]+)\s*,\s*[@%#]?(\w+)')
+# Assembler directives that carry no information worth reading.  .local/
+# .comm/.lcomm declare zero-initialised data, .literal/.literal_position
+# are Xtensa literal-pool bookkeeping — none of them is an instruction.
 NOISE = re.compile(
     r"^\s*\.(cfi_|p2align|align\b|loc\b|file\b|text\b|globl\b|global\b|"
-    r"type\b|section\b|ident\b|weak\b|hidden\b|addrsig|build_version)"
+    r"type\b|section\b|ident\b|weak\b|hidden\b|addrsig|build_version|"
+    r"local\b|comm\b|lcomm\b|literal_position|literal\b)"
 )
 # Compiler-generated bracketing labels that add nothing (.LFB0:, .Lfunc_end0:).
 NOISE_LABEL = re.compile(r"^\.(LFB|LFE|Lfunc_begin|Lfunc_end)\d*:")
@@ -252,18 +363,28 @@ def extract_functions(asm_text):
 
     A function body runs from its column-0 label to the matching .size
     directive (gcc and clang both emit one on ELF) or the next function
-    label.  Comment lines, CFI/section/alignment directives, compiler
-    bracketing labels, and inline data (switch jump tables, constants) are
-    dropped; instructions and meaningful local labels (loop targets) are
-    kept, whitespace-stripped.
+    label.  Labels typed ``@object`` (string constants, global state,
+    lookup tables) are data, not functions, and are skipped entirely;
+    an untyped label still counts as a function so hand-written asm
+    keeps working.  Comment lines, CFI/section/alignment directives,
+    compiler bracketing labels, and inline data (switch jump tables,
+    constants) are dropped; instructions and meaningful local labels
+    (loop targets) are kept, whitespace-stripped.
     """
     funcs = {}
     current = None
+    data_labels = set()
     for raw in asm_text.splitlines():
+        t = TYPE_DIRECTIVE.match(raw)
+        if t and t.group(2) != "function":
+            data_labels.add(t.group(1))
         m = FUNC_LABEL.match(raw)
         if m:
-            current = m.group(1)
-            funcs[current] = []
+            if m.group(1) in data_labels:
+                current = None
+            else:
+                current = m.group(1)
+                funcs[current] = []
             continue
         if current is None:
             continue
@@ -453,7 +574,7 @@ def target_command(config, name, config_path):
         if not isinstance(db, str):
             sys.exit(f"error: target [{name}]: compile_commands must be a "
                      "path to a compile_commands.json, or true to search "
-                     "./, ./build, ../, ../build")
+                     "upward from the current directory")
         db = os.path.expandvars(os.path.expanduser(db))
     return Target(shlex.join([resolve_cc(cc, name), *flags]), db, discovered)
 
@@ -491,6 +612,31 @@ def build_matrix(cc_args, target_args, config, config_path, db_arg=None):
     return entries
 
 
+# --verbose: print full compiler command lines and untrimmed stderr.
+VERBOSE = False
+# Without --verbose, a failed compile shows this many stderr lines — enough
+# for the include chain plus the first error, which is the actionable part.
+MAX_STDERR_LINES = 20
+
+
+def _compile_failure(cmd, stderr):
+    """Exit for a failed compile.
+
+    A borrowed-flags command runs to hundreds of tokens and a broken
+    header environment produces pages of stderr; dumping both buries the
+    actual error.  Default: compiler + source + the first stderr lines.
+    --verbose restores the complete command and output.
+    """
+    if VERBOSE:
+        sys.exit(f"error: compile failed: {shlex.join(cmd)}\n{stderr}")
+    lines = stderr.splitlines()
+    shown = "\n".join(lines[:MAX_STDERR_LINES])
+    dropped = len(lines) - MAX_STDERR_LINES
+    more = f"\n... {dropped} more stderr lines" if dropped > 0 else ""
+    sys.exit(f"error: {cmd[0]} failed on {cmd[-1]}\n{shown}{more}\n"
+             "(re-run with --verbose for the full command and output)")
+
+
 def asm_output_name(cc_cmd, harness):
     """Filesystem-safe .s name for one (compiler, source) compilation.
 
@@ -527,10 +673,45 @@ def compile_to_asm(cc_cmd, extra_flags, harness, out_dir):
            + ["-S", "-o", str(out_s), str(harness)])
     proc = subprocess.run(cmd, capture_output=True, text=True)
     if proc.returncode != 0:
-        sys.exit(f"error: compile failed: {' '.join(cmd)}\n{proc.stderr}")
+        _compile_failure(cmd, proc.stderr)
     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}",
@@ -554,14 +735,28 @@ def format_spans(spans):
     return " ".join(f"{label}:{n}" for label, n in spans) or "-"
 
 
+# Real firmware dispatch functions call dozens of distinct symbols; an
+# uncapped list makes summary rows thousands of characters wide.
+MAX_CALLS_SHOWN = 8
+
+
+def format_calls(calls):
+    """Comma-joined callee list, capped at MAX_CALLS_SHOWN for readability."""
+    if not calls:
+        return "-"
+    if len(calls) > MAX_CALLS_SHOWN:
+        return (", ".join(calls[:MAX_CALLS_SHOWN])
+                + f", +{len(calls) - MAX_CALLS_SHOWN} more")
+    return ", ".join(calls)
+
+
 def summary_table(pairs, funcs):
     """Instruction counts, outbound calls, and loop spans per pair member."""
     rows = [("function", "role", "insns", "calls", "loop spans")]
     for old, new in pairs:
         for name, role in ((old, "baseline"), (new, "candidate")):
             insns, calls = analyze(funcs[name])
-            rows.append((name, role, str(insns),
-                         ", ".join(calls) or "-",
+            rows.append((name, role, str(insns), format_calls(calls),
                          format_spans(loop_spans(funcs[name]))))
     return render_table(rows)
 
@@ -582,10 +777,10 @@ def file_summary_table(funcs):
         for sym in calls:
             if sym not in all_calls:
                 all_calls.append(sym)
-        rows.append((name, str(insns), ", ".join(calls) or "-",
+        rows.append((name, str(insns), format_calls(calls),
                      format_spans(loop_spans(lines))))
     rows.append((f"TOTAL ({len(funcs)} functions)", str(total_insns),
-                 ", ".join(all_calls) or "-", "-"))
+                 format_calls(all_calls), "-"))
     return render_table(rows)
 
 
@@ -639,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
@@ -679,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()
@@ -707,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)")
@@ -763,13 +965,27 @@ def main(argv=None):
                         default=None, metavar="PATH",
                         help="borrow each source's include/define flags from "
                              "a compile_commands.json; with no PATH, search "
-                             "./, ./build, ../, ../build.  A target whose "
+                             "each directory (and its build/) from the CWD "
+                             "up to the repository root.  A target whose "
                              "config names its own compile_commands keeps it")
     parser.add_argument("--config", metavar="PATH",
                         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, 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.2 → asmdiff-0.1.4}/pyproject.toml

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

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

@@ -388,6 +388,77 @@ class TestIncludeFlags(unittest.TestCase):
                          ["-isystem", "/s"])
 
 
+class TestSpecsAndSysroot(unittest.TestCase):
+    """Driver flags that change the header environment (-specs, --sysroot)."""
+
+    def test_specs_glued_bare_name_not_resolved(self):
+        # A bare specs name (no path separator) is found in the compiler's
+        # own search dirs; gluing a directory onto it would break it.
+        self.assertEqual(
+            asmdiff.include_flags(["-specs=picolibc.specs"], "/build"),
+            ["-specs=picolibc.specs"])
+
+    def test_specs_with_path_resolved_against_directory(self):
+        self.assertEqual(
+            asmdiff.include_flags(["-specs=./custom/my.specs"], "/build"),
+            ["-specs=/build/custom/my.specs"])
+
+    def test_specs_split_and_double_dash(self):
+        self.assertEqual(
+            asmdiff.include_flags(["-specs", "nano.specs",
+                                   "--specs=nosys.specs"], "/b"),
+            ["-specs=nano.specs", "--specs=nosys.specs"])
+
+    def test_sysroot_glued_and_split(self):
+        self.assertEqual(
+            asmdiff.include_flags(["--sysroot=sr", "--sysroot", "/abs"],
+                                  "/b"),
+            ["--sysroot=/b/sr", "--sysroot=/abs"])
+
+
+class TestResponseFiles(unittest.TestCase):
+    """GCC @file response files inside compile_commands entries."""
+
+    def test_flags_inside_response_file_are_borrowed(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            rsp = Path(tmp) / "toolchain" / "cflags"
+            rsp.parent.mkdir()
+            rsp.write_text("-mlongcalls\n-specs=picolibc.specs\n-Irspinc\n")
+            src = Path(tmp) / "a.c"
+            src.touch()
+            db = Path(tmp) / "compile_commands.json"
+            db.write_text(json.dumps([{
+                "directory": tmp, "file": str(src),
+                "command": f"cc -Iinc @{rsp} -c a.c"}]))
+            asmdiff._DB_CACHE.clear()
+            self.assertEqual(
+                asmdiff.compile_commands_flags(str(db), str(src)),
+                ["-I", f"{tmp}/inc", "-specs=picolibc.specs",
+                 "-I", f"{tmp}/rspinc"])
+
+    def test_relative_response_file_resolves_against_directory(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            (Path(tmp) / "cflags").write_text("-DFROMRSP")
+            self.assertEqual(
+                asmdiff._expand_response_files(["@cflags"], tmp),
+                ["-DFROMRSP"])
+
+    def test_nested_response_files(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            (Path(tmp) / "outer").write_text("@inner -DOUTER")
+            (Path(tmp) / "inner").write_text("-DINNER")
+            self.assertEqual(
+                asmdiff._expand_response_files(["@outer"], tmp),
+                ["-DINNER", "-DOUTER"])
+
+    def test_missing_response_file_warns_and_continues(self):
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            out = asmdiff._expand_response_files(["-DKEEP", "@/nope/x"], "/b")
+        self.assertEqual(out, ["-DKEEP"])
+        self.assertIn("/nope/x", err.getvalue())
+
+
 class TestCompileCommandsFlags(unittest.TestCase):
     def _db(self, tmp, entries):
         path = Path(tmp) / "compile_commands.json"
@@ -477,15 +548,22 @@ def _inside(directory):
 
 
 class TestFindCompileCommands(unittest.TestCase):
-    """Auto-discovery of compile_commands.json near the current directory."""
+    """Auto-discovery of compile_commands.json by walking up from the CWD."""
 
     def _touch_db(self, directory):
         directory.mkdir(parents=True, exist_ok=True)
         (directory / "compile_commands.json").write_text("[]")
 
-    def test_search_order_cwd_build_parent_parentbuild(self):
+    def _repo(self, tmp):
+        """A fake repo root: .git bounds the walk so tests never escape
+        the tempdir and pick up a stray database further up."""
+        root = Path(tmp)
+        (root / ".git").mkdir()
+        return root
+
+    def test_nearer_hits_win(self):
         with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
+            root = self._repo(tmp)
             cwd = root / "sub"
             cwd.mkdir()
             for where, expect in [(root / "build", root / "build"),
@@ -497,14 +575,236 @@ class TestFindCompileCommands(unittest.TestCase):
                     self.assertEqual(asmdiff.find_compile_commands(),
                                      str(expect / "compile_commands.json"))
 
+    def test_walks_up_from_nested_component_dir(self):
+        # components/amy/src is three levels below the project root where
+        # idf.py leaves build/compile_commands.json.
+        with tempfile.TemporaryDirectory() as tmp:
+            root = self._repo(tmp)
+            self._touch_db(root / "build")
+            cwd = root / "components" / "amy" / "src"
+            cwd.mkdir(parents=True)
+            with _inside(cwd):
+                self.assertEqual(asmdiff.find_compile_commands(),
+                                 str(root / "build" / "compile_commands.json"))
+
+    def test_stops_at_repository_root(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            self._touch_db(Path(tmp))          # db ABOVE the repo root
+            repo = Path(tmp) / "repo"
+            repo.mkdir()
+            (repo / ".git").write_text("gitdir: elsewhere")  # worktree form
+            cwd = repo / "src"
+            cwd.mkdir()
+            with _inside(cwd):
+                self.assertIsNone(asmdiff.find_compile_commands())
+
     def test_nothing_found_returns_none(self):
         with tempfile.TemporaryDirectory() as tmp:
-            cwd = Path(tmp) / "a" / "b"
+            root = self._repo(tmp)
+            cwd = root / "a" / "b"
             cwd.mkdir(parents=True)
             with _inside(cwd):
                 self.assertIsNone(asmdiff.find_compile_commands())
 
 
+class TestObjectLabels(unittest.TestCase):
+    """Data labels must not be reported as functions."""
+
+    ASM = """\
+\t.type\tscale, @function
+scale:
+\tentry\tsp, 32
+\tretw.n
+\t.size\tscale, .-scale
+\t.type\t__func__$1, @object
+\t.size\t__func__$1, 9
+__func__$1:
+\t.string\t"app_main"
+\t.local\ts_queue
+\t.comm\ts_queue,4,4
+\t.lcomm\ts_tmp,8
+"""
+
+    def test_object_labels_skipped(self):
+        funcs = asmdiff.extract_functions(self.ASM)
+        self.assertEqual(list(funcs), ["scale"])
+
+    def test_arm_percent_function_type_still_reported(self):
+        asm = "\t.type\tf, %function\nf:\n\tbx\tlr\n\t.size\tf, .-f\n"
+        self.assertEqual(list(asmdiff.extract_functions(asm)), ["f"])
+
+    def test_untyped_label_still_treated_as_function(self):
+        # Hand-written asm often has no .type at all.
+        asm = "myfunc:\n\tret\n"
+        self.assertEqual(list(asmdiff.extract_functions(asm)), ["myfunc"])
+
+    def test_local_comm_literal_lines_not_counted(self):
+        asm = ("f:\n\tmov.n\ta2, a3\n\t.literal_position\n"
+               "\t.literal .LC1, 4096\n\t.local\tx\n\t.comm\tx,4,4\n"
+               "\tretw.n\n")
+        funcs = asmdiff.extract_functions(asm)
+        insns, _ = asmdiff.analyze(funcs["f"])
+        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))
+
+    def test_default_trims_flags_and_stderr(self):
+        asmdiff.VERBOSE = False
+        with self.assertRaises(SystemExit) as ctx:
+            asmdiff._compile_failure(self.CMD, self.STDERR)
+        msg = str(ctx.exception)
+        self.assertIn("xtensa-gcc failed on a.c", msg)
+        self.assertNotIn("-I/inc0", msg)                 # no flag dump
+        self.assertIn("err line 0", msg)
+        self.assertNotIn("err line 30", msg)             # stderr trimmed
+        self.assertIn("40 more stderr lines", msg)
+        self.assertIn("--verbose", msg)
+
+    def test_verbose_shows_everything(self):
+        asmdiff.VERBOSE = True
+        try:
+            with self.assertRaises(SystemExit) as ctx:
+                asmdiff._compile_failure(self.CMD, self.STDERR)
+        finally:
+            asmdiff.VERBOSE = False
+        msg = str(ctx.exception)
+        self.assertIn("-I/inc0", msg)
+        self.assertIn("err line 59", msg)
+
+    def test_short_stderr_not_annotated_with_more(self):
+        asmdiff.VERBOSE = False
+        with self.assertRaises(SystemExit) as ctx:
+            asmdiff._compile_failure(["gcc", "x.c"], "one error\n")
+        self.assertNotIn("more stderr", str(ctx.exception))
+
+
+class TestFormatCalls(unittest.TestCase):
+    def test_short_list_unchanged(self):
+        self.assertEqual(asmdiff.format_calls(["a", "b"]), "a, b")
+
+    def test_empty_is_dash(self):
+        self.assertEqual(asmdiff.format_calls([]), "-")
+
+    def test_long_list_capped(self):
+        calls = [f"fn{i}" for i in range(12)]
+        out = asmdiff.format_calls(calls)
+        self.assertTrue(out.endswith("+4 more"))
+        self.assertIn("fn7", out)
+        self.assertNotIn("fn8,", out)
+
+
 class TestDiscoveredCompileCommands(unittest.TestCase):
     """compile_commands = true in a target / bare --compile-commands."""