[krishika08]

Summary

Release preparation for RepoNeedle 1.2.0, plus one security fix found during final release checks. This PR does not tag, publish to PyPI or update the Hugging Face Space; those are separate steps after merge.

The PR has two commits.

1. 376f092 — Bump version to 1.2.0 and update release documentation

• Version set to 1.2.0 in pyproject.toml and reponeedle/__init__.py.
• New root CHANGELOG.md, reviewed against the code. It covers CLI JSON and anchors, the MCP server, indexing security, diagnostics, abstention disabled by default, optional extras, backward compatibility, migration and known limitations. No retrieval improvement is claimed.
• Pre-release wording updated across README, KNOWN_LIMITATIONS, CLAIMS_AND_EVIDENCE and docs/.
  • MCP installation now points to pip install "reponeedle[mcp]>=1.2.0", with 1.2.0 marked upcoming until published and a from-source fallback.
  • Historical benchmark provenance is unchanged. Supplemental and experimental results are still labelled as not official ARB scores.
• tests/test_documentation_consistency.py: replaced a check that skipped itself once the version reached 1.2, because a skip fails the strict Linux job. The new checks apply to any version.

2. 2b4da11 — Never traverse directory links during indexing; bound directory traversal

Problem. from_directory used os.walk(followlinks=False), which relies on os.path.islink(). That returns False for Windows NTFS junctions, so junctions were descended into. Reproduced with synthetic files:

Case	Before	After
Junction to the repository root (cycle)	83 directory visits for 3 real directories; each file indexed up to 27×; stopped only at the path length limit	3 visits, each file indexed once, src/up recorded
Junction to the repository's parent (escape and cycle)	15 directories outside the root listed; outside file names recorded in diagnostics	0 outside directories visited; only the link path recorded

Outside file contents were already not read (file-level containment from the earlier security fix). On Linux and macOS, directory symlinks were already not followed.

Fix. Changes are limited to from_directory traversal. Ranking, packing, abstention and from_documents (used by all benchmarks) are unchanged.

• Directory symlinks and junctions are never traversed on any platform.
  • is_directory_link() uses os.lstat: S_ISLNK, or the mount-point reparse tag on Windows. Python 3.10–3.12 share one code path, which matters because Python < 3.12 has no os.path.isjunction.
  • Detection fails closed: an entry that cannot be inspected is treated as a link.
• Each physical directory (st_dev, st_ino) is entered at most once, so traversal is bounded by the real directory tree.
• New, defaulted diagnostics fields: skipped_directories, skipped_directory_paths and skipped_directories_outside_repository. They record in-repository paths only. A count-only warning, CLI notice and MCP startup note appear for links that resolve outside the repository.
• Behaviour change (Windows only): a directory reachable only through a link (for example a junction to a sibling checkout) is no longer indexed. Files under an in-repository link target are indexed once, under their real path. This is documented in CHANGELOG (security entry, compatibility and migration) and KNOWN_LIMITATIONS §5a item 2c.

Compatibility. The new model fields have defaults. Existing keys and their order are unchanged. JSON without the new keys still validates. The from_directory signature is unchanged.

Tests

• tests/test_indexing_security.py: platform-neutral tests (real symlinks on Linux; junction fallback on Windows):

  • directory link to outside the repository;
  • cycle to an ancestor;
  • cycle through the parent (including the outside-file marker check);
  • mutual link cycle;
  • valid in-repository directory link (indexed once, no warning);
  • normal nested directories;
  • broken directory link;
  • fail-closed detection;
  • repeated physical directory identity.

  The last test is simulated: os.stat is patched so one directory reports the repository root's identity. It is not a real bind mount, which would need root privileges.

• tests/test_windows_junctions.py: Windows-only junction tests, including detection without os.path.isjunction. They skip on Linux, so this file is not in the strict no-skip job.

• The strict mcp-security-linux job (REPONEEDLE_FAIL_ON_SKIP=1) runs tests/test_indexing_security.py, so the directory tests run there with real Linux symlinks.

Local validation (Windows)

Check	Result
Full suite, Python 3.12 (mcp + api extras), final tree	495 passed, 7 skipped (file-symlink creation not permitted on this Windows host)
Commit 376f092 alone, full suite	459 passed, 0 failed
Python 3.11 (no os.path.isjunction): security, junction and diagnostics suites	54 passed (skips: mcp not installed; file symlinks)
Reproduction after the fix, Python 3.11 and 3.12	Bounded; 0 outside directories visited
Build + twine check --strict (version bump step)	PASSED; wheel and metadata report 1.2.0
Clean wheel installs: base (3.11), [mcp] (3.12), [api] (3.12)	14/14, 14/14, 13/13

Not included

• No tag, PyPI publication or Hugging Face update. The demo API and Space still bundle the 1.1.0 engine.
• After merge: tag v1.2.0 to run the release workflow (version match → tests → build → publish), then remove the "upcoming" wording.

🤖 Generated with Claude Code