[khushalsonawat]

Review only the commits after bc3dd187

This branch starts from #273's head (bc3dd187, feat/TH-9449-scan-followups), so it carries #273's nine commits. Those are reviewed in #273. This PR's own change is the last two commits:

• bc778b61 fix(harness): take the build-hazard look's folders in name order
• 6c12b363 test(harness): hold the hazard look's order at its top and below it

Compare: bc3dd187...feat/TH-9514-hazard-name-order. Merge #273 first. This PR's diff then shrinks to those two commits.

Description

For each agent the scan lists, a quick "hazard" look asks whether a build of that folder may stop on its own fallback, such as two agent.py files below it. The look stops early at its caps:

• 200,000 entries;
• fix(harness): bound the scan walk by what it holds, merge its two readers, test its untested branches (TH-9449, TH-9450, TH-9451) #273's 64 Mi characters of listed paths;
• the clock.

It took folders in whatever order the file system lists them. So on a tree big enough to reach a cap, the same tree could say agent_py on a Mac and "" on Linux. That's how #273's CI failed on Linux after passing on the Mac.

Each folder's subfolders and files are now sorted before anything else, as the scan's walk (_source_files) and the framework check (folder_findings) already do. The look goes depth first in name order everywhere, so a cap stops it at the same folder.

Type of Change

• Bug fix
• Tests

Changes

• scan_walk._hazard: directories.sort() and files.sort() before the ignore list.
• build_hazard's docstring names its three stops and the order.
• New test, test_a_hazard_look_stopped_by_its_cap_gives_one_answer_in_any_listing_order[found|stopped]-[top|nested]. It forces both listing orders through a wrapped os.walk, with the tree at the top and a level below it:
  • found must give agent_py in both orders;
  • stopped must give "" in both, with neither agent.py ever listed, so the "" comes from the cap.
• One stale test comment, "(os.walk doesn't sort them)", is removed.

Testing

• One file at a time, on Python 3.12.14 and 3.12.3:

  test file	passed
  test_scan_walk	151
  test_agent_scan	63
  test_scan_folders	8
  test_scan_document	17
  test_scan_ai	59
  test_authoring_entrypoint_find_agents	5
  test_framework_detection	262
  test_reading_entry	61

  test_harness_architecture gives 35 passed and 11 failed, the same as at bc3dd187 without this change. The 11 are TH-9444's hosted-GitHub tests, which CI deselects at this base.

• Planted breaks, each run against each of the four cases:

  • the sort removed: caught by all four;
  • the sort after the filter: caught by all four;
  • the sort skipped at the top: caught by the two top cases;
  • the sort only at the top: caught by the two nested cases.

• git merge-tree into feat/TH-8804-source-subfolder is clean.

• Review, on Lane N: the design review, the plan review and the change review each cleared in round 1. Both change reviewers ran every plant.

What wasn't reviewed

6c12b363 fixes the change review's one shared Medium, a test that missed the top folder. It changes tests only.

Not changed here

#273's listed-paths cap counts absolute paths. So where it stops still depends on the checkout's root length, not just the order. That's left as it is.

Related Issues

Refs: TH-9514

[cdileep23]

Please check the comments.