feat: add python bisect harvest 1 (#612)

* feat: add python bisect harvest 1

* docs: clear stale python bisect wishlist

* data: sync website upstream bisect inventory

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: kvz

CHANGELOG.md

@@ -39,6 +39,10 @@ Version rationale: `patch` for additive Python runtime expansion without import-
 
 ## main
 
+### Expansion
+
+- Added a first `python/bisect` harvest covering `bisect`, `bisect_left`, and `bisect_right`.
+
 Released: TBA. [Diff](https://github.com/locutusjs/locutus/compare/v3.0.32...main).
 
 ### Fixes

docs/non-php-api-signatures.snapshot

@@ -257,6 +257,9 @@ src/powershell/string/toupper.ts :: export function toupper(str: string): string
 src/powershell/string/trim.ts :: export function trim(str: string): string
 src/powershell/string/trimend.ts :: export function trimend(str: string, chars?: string): string
 src/powershell/string/trimstart.ts :: export function trimstart(str: string, chars?: string): string
+src/python/_helpers/_bisect.ts :: export function pythonBisect(sequence: unknown, item: unknown, lo?: unknown, hi?: unknown): number
+src/python/_helpers/_bisect.ts :: export function pythonBisectLeft(sequence: unknown, item: unknown, lo?: unknown, hi?: unknown): number
+src/python/_helpers/_bisect.ts :: export function pythonBisectRight(sequence: unknown, item: unknown, lo?: unknown, hi?: unknown): number
 src/python/_helpers/_calendar.ts :: export function buildMonthCalendar(year: number, month: number): number[][]
 src/python/_helpers/_calendar.ts :: export function buildWeekHeader(width: number): string
 src/python/_helpers/_calendar.ts :: export function countLeapYearsBetween(startYear: number, endYear: number): number
@@ -337,6 +340,9 @@ src/python/_helpers/_statistics.ts :: export function toNumericSequence(data: un
 src/python/_helpers/_statistics.ts :: export function toStatisticNumber(value: unknown, functionName: string): number
 src/python/_helpers/_statistics.ts :: export type StatisticsNumericInput = number | boolean | bigint
 src/python/_helpers/_statistics.ts :: export type StatisticsSortableInput = StatisticsNumericInput | string
+src/python/bisect/bisect.ts :: export function bisect(a: unknown, x: unknown, lo?: unknown, hi?: unknown): number
+src/python/bisect/bisect_left.ts :: export function bisect_left(a: unknown, x: unknown, lo?: unknown, hi?: unknown): number
+src/python/bisect/bisect_right.ts :: export function bisect_right(a: unknown, x: unknown, lo?: unknown, hi?: unknown): number
 src/python/calendar/calendar.ts :: export function calendar(theyear: unknown, w = 2, l = 1, c = 6, m = 3): string
 src/python/calendar/formatstring.ts :: export function formatstring(items: unknown, cols = 20, spacing = 6): string
 src/python/calendar/isleap.ts :: export function isleap(year: unknown): boolean

docs/prompts/LOG.md

@@ -3219,3 +3219,28 @@ LLMs log key learnings, progress, and next steps in one `### Iteration ${increme
 - Key learnings:
   - QEMU was necessary but not sufficient: prewarming and runtime execution must agree on platform, otherwise Docker silently falls back to an implicit second pull at execution time.
   - `discoverUsesDocker` and `discoverDockerPlatform` together are now part of the discovery contract for platform-specific runtimes like Swift.
+
+### Iteration 159
+
+2026-03-30
+
+- **Area: Product (Python bisect harvest 1)**
+- Plan:
+  - Harvest the parity-friendly `python/bisect` surface now that nightly maintenance is green again.
+  - Keep the scope to the non-mutating search helpers and avoid `insort*` side effects.
+- Progress:
+  - Added `src/python/bisect` with `bisect`, `bisect_left`, and `bisect_right`, backed by a shared `_bisect` helper that mirrors Python 3.12 insertion-point semantics for arrays and strings.
+  - Preserved key parity edges around duplicate ranges, `lo`/`hi` bounds, `hi=None`, NaN ordering behavior, and Python-style incomparable-type errors.
+  - Updated `src/python/index.ts`, both Rosetta maps, generated bisect tests, website pages, non-PHP API signatures, and type-contract snapshots.
+- Validation:
+  - `corepack yarn exec vitest run test/util/python-bisect-harvest-1.vitest.ts`
+  - `corepack yarn test:parity python/bisect/bisect python/bisect/bisect_left python/bisect/bisect_right --no-cache`
+  - `node scripts/rmrf.ts test/generated && corepack yarn build:tests`
+  - `corepack yarn exec vitest run test/generated/python/bisect/*.vitest.ts`
+  - `corepack yarn injectweb && corepack yarn website:verify`
+  - `corepack yarn fix:api:snapshot:nonphp`
+  - `corepack yarn fix:type:contracts`
+  - `corepack yarn check`
+- Key learnings:
+  - The generated standalone test path will expose symbol collisions that the source/module variants can miss, so alias-like function names need helper internals with distinct names.
+  - `bisect` is a good example of a small Python module where strict target-definition work pays off: once the inventory and wishlist are explicit, the harvest becomes a narrow parity exercise rather than guesswork.

docs/upstream-surface-inventory.yml

@@ -1454,9 +1454,6 @@ python:
         note: Most base64 helpers traffic in bytes rather than plain JS string values.
     bisect:
       title: bisect module
-      default:
-        decision: wanted
-        note: Binary-search helpers are strong plain-value portability targets.
       decisions:
         insort:
           decision: skip_side_effects

src/python/_helpers/_bisect.ts

@@ -0,0 +1,135 @@
+import { isNumericLike, toPythonInteger, toPythonNumber } from './_operator.ts'
+
+type BisectSequence = unknown[] | string
+
+export function pythonBisect(sequence: unknown, item: unknown, lo?: unknown, hi?: unknown): number {
+  return bisectCore(sequence, item, lo, hi, 'bisect', 'right')
+}
+
+export function pythonBisectLeft(sequence: unknown, item: unknown, lo?: unknown, hi?: unknown): number {
+  return bisectCore(sequence, item, lo, hi, 'bisect_left', 'left')
+}
+
+export function pythonBisectRight(sequence: unknown, item: unknown, lo?: unknown, hi?: unknown): number {
+  return bisectCore(sequence, item, lo, hi, 'bisect_right', 'right')
+}
+
+function bisectCore(
+  sequence: unknown,
+  item: unknown,
+  lo: unknown,
+  hi: unknown,
+  functionName: string,
+  side: 'left' | 'right',
+): number {
+  const values = toBisectSequence(sequence, functionName)
+  let left = normalizeLo(lo, functionName)
+  let right = normalizeHi(hi, values.length, functionName)
+
+  while (left < right) {
+    const middle = Math.floor((left + right) / 2)
+    const candidate = getSequenceItem(values, middle)
+
+    if (
+      side === 'left' ? pythonLessThan(candidate, item, functionName) : !pythonLessThan(item, candidate, functionName)
+    ) {
+      left = middle + 1
+    } else {
+      right = middle
+    }
+  }
+
+  return left
+}
+
+function toBisectSequence(sequence: unknown, functionName: string): BisectSequence {
+  if (Array.isArray(sequence) || typeof sequence === 'string') {
+    return sequence
+  }
+
+  throw new TypeError(`${functionName}() expected an indexable sequence`)
+}
+
+function normalizeLo(value: unknown, functionName: string): number {
+  if (value === undefined) {
+    return 0
+  }
+
+  const index = toSequenceIndex(value, functionName)
+  if (index < 0) {
+    throw new RangeError('lo must be non-negative')
+  }
+
+  return index
+}
+
+function normalizeHi(value: unknown, sequenceLength: number, functionName: string): number {
+  if (value === undefined || value === null) {
+    return sequenceLength
+  }
+
+  return toSequenceIndex(value, functionName)
+}
+
+function toSequenceIndex(value: unknown, functionName: string): number {
+  const index = Number(toPythonInteger(value, functionName))
+  if (!Number.isSafeInteger(index)) {
+    throw new RangeError(`${functionName}() index must fit within JS safe integer precision`)
+  }
+
+  return index
+}
+
+function getSequenceItem(sequence: BisectSequence, index: number): unknown {
+  if (index < 0 || index >= sequence.length) {
+    throw new Error(Array.isArray(sequence) ? 'list index out of range' : 'string index out of range')
+  }
+
+  return sequence[index]
+}
+
+function pythonLessThan(left: unknown, right: unknown, functionName: string): boolean {
+  if (isNumericLike(left) && isNumericLike(right)) {
+    const leftNumber = toPythonNumber(left, functionName)
+    const rightNumber = toPythonNumber(right, functionName)
+    if (Number.isNaN(leftNumber) || Number.isNaN(rightNumber)) {
+      return false
+    }
+
+    return leftNumber < rightNumber
+  }
+
+  if (typeof left === 'string' && typeof right === 'string') {
+    return left < right
+  }
+
+  throw new TypeError(`'<' not supported between instances of '${pythonTypeName(left)}' and '${pythonTypeName(right)}'`)
+}
+
+function pythonTypeName(value: unknown): string {
+  if (typeof value === 'string') {
+    return 'str'
+  }
+
+  if (typeof value === 'boolean') {
+    return 'bool'
+  }
+
+  if (typeof value === 'bigint' || typeof value === 'number') {
+    return 'int'
+  }
+
+  if (Array.isArray(value)) {
+    return 'list'
+  }
+
+  if (value === null) {
+    return 'NoneType'
+  }
+
+  if (value === undefined) {
+    return 'undefined'
+  }
+
+  return typeof value
+}

src/python/bisect/bisect.ts

@@ -0,0 +1,11 @@
+import { pythonBisect } from '../_helpers/_bisect.ts'
+
+export function bisect(a: unknown, x: unknown, lo?: unknown, hi?: unknown): number {
+  //      discuss at: https://locutus.io/python/bisect/bisect/
+  // parity verified: Python 3.12
+  //     original by: Kevin van Zonneveld (https://kvz.io)
+  //       example 1: bisect([1, 2, 2, 4], 2)
+  //       returns 1: 3
+
+  return pythonBisect(a, x, lo, hi)
+}

src/python/bisect/bisect_left.ts

@@ -0,0 +1,11 @@
+import { pythonBisectLeft } from '../_helpers/_bisect.ts'
+
+export function bisect_left(a: unknown, x: unknown, lo?: unknown, hi?: unknown): number {
+  //      discuss at: https://locutus.io/python/bisect/bisect_left/
+  // parity verified: Python 3.12
+  //     original by: Kevin van Zonneveld (https://kvz.io)
+  //       example 1: bisect_left([1, 2, 2, 4], 2)
+  //       returns 1: 1
+
+  return pythonBisectLeft(a, x, lo, hi)
+}

src/python/bisect/bisect_right.ts

@@ -0,0 +1,11 @@
+import { pythonBisectRight } from '../_helpers/_bisect.ts'
+
+export function bisect_right(a: unknown, x: unknown, lo?: unknown, hi?: unknown): number {
+  //      discuss at: https://locutus.io/python/bisect/bisect_right/
+  // parity verified: Python 3.12
+  //     original by: Kevin van Zonneveld (https://kvz.io)
+  //       example 1: bisect_right([1, 2, 2, 4], 2)
+  //       returns 1: 3
+
+  return pythonBisectRight(a, x, lo, hi)
+}

src/python/bisect/index.ts

@@ -0,0 +1,3 @@
+export { bisect } from './bisect.ts'
+export { bisect_left } from './bisect_left.ts'
+export { bisect_right } from './bisect_right.ts'

src/python/index.ts

@@ -1,3 +1,4 @@
+export * as bisect from './bisect/index.ts'
 export * as calendar from './calendar/index.ts'
 export * as difflib from './difflib/index.ts'
 export * as itertools from './itertools/index.ts'