docs(spec): entrypoint detection for typescript, matching python

[rahlk]

Spec for TypeScript entrypoint detection at parity with codeanalyzer-python's #27. Committed as provenance; no code.

Starting point

TypeScript has none. grep -rniE "entry_?point" src/ returns one hit, and it is a bundler comment in dataflow/pool.ts.

	python	typescript
entrypoint code	codeanalyzer/entrypoints/, 5 files	—
source references	73	0
schema	PyEntrypoint, PyEntrypointReport	—
Neo4j	is_entrypoint, entrypoint_frameworks	—
CLI	--entrypoint-rules	—

Without this, the analyzer emits a call graph with no distinguished roots — so a consumer cannot ask what is reachable from outside the application, which is the first question any taint or attack-surface query asks.

What the spec commits to

Mirror python's contract exactly: TSEntrypoint/TSEntrypointReport, entrypoints + is_entrypoint on TSCallable and TSType, the same Neo4j properties, a declarative rules file with a stage-0 framework gate, --entrypoint-rules for user rules, graded declared|certain|heuristic confidence, via: dispatch modelling, and a coverage report. Level-free L1 post-pass; rule loading is a hard error, detection is best-effort and never aborts the analysis.

The part that cannot be ported

Python's engine has two matchers — decorators and base classes — and they cover its ecosystem. They do not cover TypeScript's:

framework	declared how	matcher
NestJS, Angular	decorators	python has it
Express, Koa, Fastify	app.get('/p', h) — a call	call-site
Next.js, Remix, SvelteKit	app/**/route.ts, +server.ts	file convention
AWS Lambda	exported handler	export name
CLI tools, packages	bin/main in package.json	manifest

So the rules format has to be designed for three matcher kinds python never needed, rather than copied and extended later. Two decisions are called out explicitly: whether a file-convention entrypoint can hang off a module (python's schema has no module-level entrypoints, so this would diverge from the shared vocabulary), and how call-site matching stays level-free — recommendation is a syntactic L1 match at confidence: heuristic rather than gating Express to -a >= 2 and breaking "identical at every -a".

What TS has going for it

Better positioned than python was: decorators are structured and checker-resolved as of #143 — qualified_name is the direct analog of the Jedi definition path python matches on, and positional_arguments/keyword_arguments are exactly what route: {from: positional, index: 0} needs. Heritage is resolved to can:// ids, so transitive base matching is a graph walk rather than a name match. And the stage-0 gate has two ready sources in TSImport and the artifact layer's TSDependency, where python had to regex manifests.

Recommendation on #72

#72 ("entrypoint finders (Express/Angular routes)") is scoped too narrowly — two frameworks and no engine. Built as written it would produce hardcoded detectors with no rules file, no confidence grading, no coverage report and no extensibility, then need rewriting for parity. Retitle it or close it in favour of the engine-shaped unit.

Caveats it states plainly

• Under-approximation is the designed failure mode and is invisible without the report, so the report ships in the same change as detection, never after
• False positives are worse than misses — a locally defined Controller in a non-NestJS project must not register, which is why the stage-0 gate is not an optimisation
• The call-site matcher is the weakest link and should ship as heuristic; Express handlers registered via a variable or helper will be missed, and that belongs in the report's unresolved counts
• Not validated against a labelled corpus