mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

Jeffrey (Dongkyu) Kim 19de41c166 Prevent filtered NEC lookup false negatives

Fix the candidate parser so documented education-superintendent and filtered local-election lookups return bounded, evidence-backed results instead of silently dropping valid rows.

Constraint: PR #266 round-3 review required TDD, Ralph verification, and branch update for issue #256.

Rejected: Full NEC pagination in this follow-up | broader than the approved change; bounded 100-row fetch now avoids user-limit false negatives and warns when capped.

Confidence: high

Scope-risk: narrow

Directive: Preserve exact-name fail-closed parsing and count raw parsed upstream rows before cap-warning decisions.

Tested: git diff --check; node --test packages/local-election-candidate-search/test/index.test.js; npm run lint --workspace local-election-candidate-search; npm run test --workspace local-election-candidate-search; npm pack --workspace local-election-candidate-search --dry-run; live CLI smokes for 오세훈, 조희연, 김동연; CLI help/no-args checks; architect verification CLEAR.

Not-tested: Full npm run ci remains blocked by pre-existing repo-wide missing SKILL.md: ohou-today-deal.

2026-05-18 16:54:50 +09:00

2.7 KiB

Raw Blame History

local-election-candidate-search

Public Korean local election candidate lookup client for the local-election-candidate-search k-skill.

Source

Official public surface: 중앙선거관리위원회 선거통계시스템 통합검색 https://info.nec.go.kr/search/searchCandidate.xhtml
Request method: unauthenticated POST with searchKeyword=<exact candidate name>.
The NEC page states that integrated search looks up historical/recent preliminary candidates, candidates, and elected persons by exact name.

This client calls the public NEC HTML surface directly from the user's machine. No proxy, API key, login, CAPTCHA bypass, registration, or filing automation is used.

Usage

const { searchCandidates } = require("local-election-candidate-search")

const result = await searchCandidates({
  name: "오세훈",
  election: "시도지사",
  region: "서울",
  limit: 5
})

CLI:

local-election-candidate-search 오세훈 --election 시도지사 --region 서울 --limit 5
local-election-candidate-search 김동연 --date 2014 --election 기초의원
local-election-candidate-search 이재명 --all

Returned fields

Each item includes parsed candidate/profile and election fields when present: name, hanja, birth_date, gender, election_date, election_name, election_code, election_type, party, district, votes, vote_share, job, education, and career.

By default, the client filters to local-election-related NEC election codes: 시·도지사(3), 구·시·군의 장(4), 시·도의회의원(5), 구·시·군의회의원(6), 광역비례(8), 기초비례(9), 교육감(11). Use --all / localOnly:false to include non-local races from NEC integrated search.

summary.upstream_result_limit records how many NEC rows were requested before local client-side filters were applied. When election/date/region/local filters are active, the client fetches up to 100 upstream rows first and then applies the user-facing limit after exact-name matching, filtering, and deduplication.

Boundaries and failure modes

NEC integrated search works best with exact Korean candidate names and may return homonyms; use --election, --date, and --region to narrow results.
The upstream is HTML, so parser warnings are returned for empty results, maintenance pages, NetFunnel queues, login prompts, or unexpected markup changes.
If the fetched upstream page reaches the 100-row cap while client-side filters are active, the result includes a warning that additional matches may require pagination.
This package does not automate NEC detail popups, file downloads, account login, CAPTCHA, political filing, or any privileged workflow.

2.7 KiB Raw Blame History