Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(ingestion): rank manifest-declared entry points first (#2698)

Swati Ahuja2cdf77dfa655
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 82f7483ca..188ba2f96 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -120,6 +120,10 @@ log = structlog.get_logger(__name__)
# and a declining call's arguments are not scanned, so an assertion passed as an
# argument still does not stand in for the header's oracle.
#
+# v36: files a package manifest declares (package.json ``bin``, a built
+# ``main`` mapped to its source, a distribution's package ``__init__``) are
+# entry points, so perf findings reachable from them are marked so.
+#
# v35: the update's full re-score reads every stored git column, so the
# percentile gates of ``prior_defect`` and ``co_change_scatter`` see their
# inputs, and it keeps the stored blame-marker findings it cannot recompute.
diff --git a/packages/core/src/repowise/core/analysis/kg_curation.py b/packages/core/src/repowise/core/analysis/kg_curation.py
index 502ddc3c2..a98f143df 100644
--- a/packages/core/src/repowise/core/analysis/kg_curation.py
+++ b/packages/core/src/repowise/core/analysis/kg_curation.py
@@ -373,7 +373,10 @@ def _curate_entry_points(
``main.py``. Config/data files (``server.json``) and generic-glue leaves
(a resolver's deep ``index.py``) are dropped from candidacy outright.
``project.entry_points`` holds the top few, ``project.entry_candidates`` the
- full ranked list. When ingestion flagged no entries at all, the strong
+ full ranked list. A manifest-declared entry (``FileInfo.is_manifest_entry``)
+ ranks first and is exempt from the barrel and glue drops: a package's
+ declared ``src/index.ts`` is its front door whatever its shape or depth.
+ When ingestion flagged no entries at all, the strong
:func:`score_entry_points` scorers (entry-style filenames) fill in, so the
orientation panel never opens empty on repos without a detectable main.
"""
@@ -382,7 +385,10 @@ def _curate_entry_points(
pagerank = graph_builder.pagerank() or {}
betweenness = _betweenness(graph_builder)
- paths = _flagged_entry_paths(kg, pf_by_path)
+ manifest = frozenset(
+ path for path, pf in pf_by_path.items() if getattr(pf.file_info, "is_manifest_entry", False)
+ )
+ paths = _flagged_entry_paths(kg, pf_by_path, manifest)
if not paths:
# No flagged entries survived: score >= 3 means an entry-style name or
# flag, never just a shallow or high-PageRank file.
@@ -393,7 +399,7 @@ def _curate_entry_points(
]
candidates = [(path, pagerank.get(path, 0.0), betweenness.get(path, 0.0)) for path in paths]
- ranked = rank_entry_points(candidates, conventional_entry_stems())
+ ranked = rank_entry_points(candidates, conventional_entry_stems(), manifest)
kg.project["entry_points"] = ranked[:_MAX_ENTRY_POINTS]
kg.project["entry_candidates"] = ranked
@@ -405,11 +411,14 @@ def _betweenness(graph_builder: Any) -> dict[str, float]:
return {}
-def _flagged_entry_paths(kg: KnowledgeGraphResult, pf_by_path: dict[str, Any]) -> list[str]:
+def _flagged_entry_paths(
+ kg: KnowledgeGraphResult, pf_by_path: dict[str, Any], manifest: frozenset[str]
+) -> list[str]:
"""Ingestion-flagged entry files that survive candidacy, in node order.
A flagged re-export barrel is retagged ``barrel`` in the presentation view
- (the AST graph's flag is untouched) and dropped.
+ (the AST graph's flag is untouched) and dropped, unless a manifest declares
+ it. Test and example paths are dropped either way.
"""
paths: list[str] = []
for node in kg.nodes:
@@ -419,6 +428,9 @@ def _flagged_entry_paths(kg: KnowledgeGraphResult, pf_by_path: dict[str, Any]) -
language = (node.get("language") or "").lower()
if _off_the_entry_path(path, language):
continue
+ if path in manifest:
+ paths.append(path)
+ continue
if _is_barrel_path(path, pf_by_path):
_retag_as_barrel(node)
continue
diff --git a/packages/core/src/repowise/core/generation/entry_points.py b/packages/core/src/repowise/core/generation/entry_points.py
index 98f77c0a5..48b7c6590 100644
--- a/packages/core/src/repowise/core/generation/entry_points.py
+++ b/packages/core/src/repowise/core/generation/entry_points.py
@@ -63,11 +63,15 @@ def entry_point_rank_key(
pagerank: float = 0.0,
betweenness: float = 0.0,
conventional_stems: frozenset[str] = frozenset(),
-) -> tuple[int, int, float, str]:
+ manifest_entries: frozenset[str] = frozenset(),
+) -> tuple[int, int, int, float, str]:
"""Sort key for an entry-point candidate (ascending tuple = better entry).
Most significant component first:
+ 0. **tier** — a file a package manifest names (``bin``, ``main``,
+ ``exports["."]``, a console script) is declared, not guessed, so it
+ outranks every filename guess.
1. **name bucket** — a conventional entry name (``main``/``app``/``cli``/
``manage``/…) never loses to a generic glue stem (``index``/``mod``),
and glue never outranks a real entry.
@@ -78,6 +82,7 @@ def entry_point_rank_key(
4. **path** — deterministic final tiebreak.
"""
return (
+ 0 if path in manifest_entries else 1,
_name_bucket(path, conventional_stems),
entry_point_depth(path),
-(pagerank + betweenness),
@@ -164,6 +169,7 @@ def orientation_entry_points(repo_structure: Any, *, limit: int | None = None) -
def rank_entry_points(
candidates: list[tuple[str, float, float]],
conventional_stems: frozenset[str],
+ manifest_entries: frozenset[str] = frozenset(),
) -> list[str]:
"""Rank ``(path, pagerank, betweenness)`` candidates, best entry first."""
return [
@@ -175,6 +181,7 @@ def rank_entry_points(
pagerank=c[1],
betweenness=c[2],
conventional_stems=conventional_stems,
+ manifest_entries=manifest_entries,
),
)
]
diff --git a/packages/core/src/repowise/core/ingestion/graph_warmups.py b/packages/core/src/repowise/core/ingestion/graph_warmups.py
index 6288a1790..a825acc12 100644
--- a/packages/core/src/repowise/core/ingestion/graph_warmups.py
+++ b/packages/core/src/repowise/core/ingestion/graph_warmups.py
@@ -321,6 +321,12 @@ def _warmup_typescript(ctx: ResolverContext) -> None:
to. Without this, files reachable only through the package boundary
(downstream npm consumers) read as ``in_degree==0`` and ship as
unreachable findings.
+
+ Files a ``package.json`` declares as where it starts (``bin``, ``main``,
+ ``exports["."]``) are stamped on the parsed ``FileInfo`` too, as
+ manifest entries: they are what the entry-point list ranks first. The
+ other sources here stay graph-only, since they keep code alive without
+ being anywhere a reader enters.
"""
from .resolvers.ts_workspace import (
find_mdx_import_targets,
@@ -333,7 +339,13 @@ def _warmup_typescript(ctx: ResolverContext) -> None:
graph = getattr(ctx, "graph", None)
if graph is None:
return
- entry_paths: set[str] = set(index.exports_entry_paths)
+ parsed = getattr(ctx, "parsed_files", None) or {}
+ for path in index.manifest_entry_paths:
+ pf = parsed.get(path)
+ if pf is not None and getattr(pf, "file_info", None) is not None:
+ pf.file_info.is_entry_point = True
+ pf.file_info.is_manifest_entry = True
+ entry_paths: set[str] = set(index.exports_entry_paths) | index.manifest_entry_paths
# MDX-only consumers (docs sites that import TSX components into
# ``.mdx``) and custom vitest layouts (``runtime-tests/**``) — both
# invisible to the TS parser, both real entry points.
diff --git a/packages/core/src/repowise/core/ingestion/languages/registry.py b/packages/core/src/repowise/core/ingestion/languages/registry.py
index cacdd1b18..53c5487b1 100644
--- a/packages/core/src/repowise/core/ingestion/languages/registry.py
+++ b/packages/core/src/repowise/core/ingestion/languages/registry.py
@@ -23,21 +23,25 @@ from .spec import LanguageSpec
from .specs import ALL_SPECS as _SPECS
# Entry-point filename stems that are conventional across languages rather
-# than owned by any one of them ("bootstrap.php", "entry.ts", "cli.py",
-# "server.go", "main.rs", "app.py", "index.js" …). Language-unique stems
+# than owned by any one of them ("bootstrap.php", "cli.py", "server.go",
+# "main.rs", "app.py", "index.js" …). Language-unique stems
# (manage/wsgi/asgi/__main__ → python, mod → rust) live on their specs.
_GENERIC_ENTRY_STEMS: frozenset[str] = frozenset(
- {"main", "index", "app", "server", "cli", "bootstrap", "entry"}
+ {"main", "index", "app", "server", "cli", "bootstrap"}
)
# Stems that are entry-point evidence on their own, for any language. The
# traverser flags on this *unioned* with the tour-bonus stems above (see
# ``traverser._ENTRY_POINT_STEMS``): the two were hand-kept and disagreed both
# ways, so this one keeps run/start, which the tour set lacks, and inherits
-# cli/bootstrap/entry, which it lacked. Per-language flag stems (wsgi/asgi →
+# cli/bootstrap, which it lacked. Per-language flag stems (wsgi/asgi →
# python) live on the specs.
+#
+# ``entry`` is a flag stem only: a bundler's ``entry.ts`` keeps its dead-code
+# exemption, but the name ranks neutral, since an ``entry.ts`` is as often a
+# module defining ``class Entry`` as a front door.
_GENERIC_ENTRY_FLAG_STEMS: frozenset[str] = frozenset(
- {"main", "index", "app", "run", "server", "start"}
+ {"main", "index", "app", "run", "server", "start", "entry"}
)
# =========================================================================
diff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.py
index e5ec83785..c84a37821 100644
--- a/packages/core/src/repowise/core/ingestion/models.py
+++ b/packages/core/src/repowise/core/ingestion/models.py
@@ -157,6 +157,10 @@ class FileInfo:
is_config: bool
is_api_contract: bool
is_entry_point: bool
+ # Named by a package manifest (package.json bin/main/exports["."],
+ # pyproject scripts, a distribution's package ``__init__``): the strongest
+ # entry evidence, ranked above every filename guess.
+ is_manifest_entry: bool = False
@dataclass
diff --git a/packages/core/src/repowise/core/ingestion/resolvers/ts_workspace.py b/packages/core/src/repowise/core/ingestion/resolvers/ts_workspace.py
index af679c1a2..4d3b252b0 100644
--- a/packages/core/src/repowise/core/ingestion/resolvers/ts_workspace.py
+++ b/packages/core/src/repowise/core/ingestion/resolvers/ts_workspace.py
@@ -33,6 +33,7 @@ import contextlib
import json
import posixpath
import re
+import subprocess
from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING, Any
@@ -129,6 +130,30 @@ def _get_repo_scan(ctx: ResolverContext) -> _RepoFileScan:
return scan
+def _parsed_package_jsons(ctx: ResolverContext) -> list[tuple[str, dict]]:
+ """``(repo-relative dir, data)`` for every readable ``package.json`` object.
+
+ Memoized per resolver context, so every finder shares one parse. The
+ base is ``ctx.repo_path`` as given, not ``.resolve()``d: the shared scan
+ walks that same path, and a different base would drop every manifest.
+ """
+ cached = getattr(ctx, "_ts_parsed_package_jsons", None)
+ if cached is not None:
+ return cached
+ parsed: list[tuple[str, dict]] = []
+ for pkg_file in _get_repo_scan(ctx).package_jsons:
+ # node_modules manifests are already pruned by the shared scan.
+ try:
+ pkg_dir = pkg_file.parent.relative_to(ctx.repo_path).as_posix()
+ data = json.loads(pkg_file.read_text(encoding="utf-8", errors="ignore"))
+ except (ValueError, OSError, json.JSONDecodeError):
+ continue
+ if isinstance(data, dict):
+ parsed.append((pkg_dir, data))
+ ctx._ts_parsed_package_jsons = parsed # type: ignore[attr-defined]
+ return parsed
+
+
# Order in which we collapse Node "conditional exports" objects down to
# a single target. Source-pointing conditions come first so a TS-aware
# static analyser sees the original ``.ts`` file rather than a built
@@ -681,6 +706,9 @@ class TsWorkspaceIndex:
packages: dict[str, dict[str, Any]] = field(default_factory=dict)
exports_entry_paths: set[str] = field(default_factory=set)
+ # Files any ``package.json`` in the repo (workspace member or not) names as
+ # where the package starts: ``bin``, ``main``/``module``, ``exports["."]``.
+ manifest_entry_paths: set[str] = field(default_factory=set)
def _expand_exports_wildcard(
@@ -720,6 +748,137 @@ def _expand_exports_wildcard(
return matches
+# Build output a package.json may point at, and the source extensions tsc
+# compiles to it. Only the unambiguous ``X.js`` ← ``X.ts`` shape is mapped.
+_BUILD_OUTPUT_JS = re.compile(r"^(?:dist|build|lib|out)/(.+)\.[mc]?js$")
+_BUILD_SOURCE_EXTENSIONS: tuple[str, ...] = (".ts", ".tsx", ".mts", ".js")
+
+
+def _manifest_targets(pkg_data: dict) -> tuple[list[str], tuple[str, ...]]:
+ """``(start targets, exports["."] targets)`` one ``package.json`` names.
+
+ Start targets are every ``bin`` target (string or map), ``main`` and
+ ``module``; the export targets come best first, declaration files skipped.
+ """
+ bin_ = pkg_data.get("bin")
+ bins = bin_.values() if isinstance(bin_, dict) else (bin_,)
+ starts = [
+ t for t in (*bins, pkg_data.get("main"), pkg_data.get("module")) if isinstance(t, str)
+ ]
+ exports = pkg_data.get("exports")
+ # A conditions-only object (``{"import": ..., "require": ...}``) is ``"."``.
+ if isinstance(exports, dict) and any(str(k).startswith(".") for k in exports):
+ exports = exports.get(".")
+ ordered = _ordered_export_targets(exports) if exports is not None else ()
+ return starts, tuple(t for t in ordered if not t.endswith(_DECLARATION_SUFFIXES))
+
+
+def _built_output(pkg_dir: str, target: str) -> tuple[str, re.Match[str]] | None:
+ """``(repo-relative path, match)`` when *target* names build output inside the repo."""
+ rel = target.removeprefix("./")
+ built = _BUILD_OUTPUT_JS.match(rel)
+ if built is None:
+ return None
+ path = _normalize_repo_rel(f"{pkg_dir}/{rel}")
+ # ``..`` in a manifest must not send the on-disk check outside the repo.
+ if path == ".." or path.startswith("../"):
+ return None
+ return path, built
+
+
+def _named_build_outputs(manifests: list[tuple[str, dict]]) -> set[str]:
+ """Every in-repo build-output path the manifests' targets name."""
+ named: set[str] = set()
+ for pkg_dir, data in manifests:
+ starts, exports = _manifest_targets(data)
+ for target in (*starts, *exports):
+ built = _built_output(pkg_dir, target)
+ if built is not None:
+ named.add(built[0])
+ return named
+
+
+def checked_in_builds(
+ repo_path: Path | None, manifests: list[tuple[str, dict]], path_set: set[str]
+) -> frozenset[str]:
+ """Build outputs the manifests name that exist on disk and are not gitignored.
+
+ A committed build is part of the checkout; a gitignored local build is
+ not. One ``git check-ignore --stdin`` call answers for the whole repo, so
+ nested ``.gitignore`` files count; outside a git work tree (or without
+ git) every existing file counts as checked in.
+ """
+ if repo_path is None:
+ return frozenset()
+ on_disk = {
+ path
+ for path in _named_build_outputs(manifests)
+ if path not in path_set and (repo_path / path).is_file()
+ }
+ if not on_disk:
+ return frozenset()
+ try:
+ verdict = subprocess.run(
+ ["git", "-C", str(repo_path), "check-ignore", "-z", "--stdin"],
+ # Bytes, NUL-separated: a text-mode pipe on Windows writes CRLF,
+ # and git would read each path with a trailing CR.
+ input="\0".join(sorted(on_disk)).encode("utf-8") + b"\0",
+ capture_output=True,
+ timeout=30,
+ )
+ # Exit 1 = none ignored; 128 = not a work tree (nothing is ignored).
+ out = verdict.stdout.decode("utf-8", errors="replace") if verdict.returncode == 0 else ""
+ ignored = set(filter(None, out.split("\0")))
+ except (OSError, subprocess.SubprocessError):
+ ignored = set()
+ return frozenset(on_disk - ignored)
+
+
+def probe_manifest_target(
+ pkg_dir: str, target: str, path_set: set[str], checked_in: frozenset[str]
+) -> str | None:
+ """The indexed file a ``package.json`` target names, reading built output as its source.
+
+ ``dist|build|lib|out/X.(m|c)js`` maps to ``src/X.(ts|tsx|mts|js)``, but only
+ when the built file is not in the checkout (*checked_in*, from
+ :func:`checked_in_builds`): a committed build is the entry itself, and
+ remapping it would name a file the package does not run.
+ Exact hits only, so an ambiguous source never stands in for the build.
+ """
+ if target.endswith(_DECLARATION_SUFFIXES):
+ return None # a declaration never starts a package, committed or not
+ hit = _probe_path(f"{pkg_dir}/{target.removeprefix('./')}", path_set)
+ if hit is not None:
+ return hit
+ built = _built_output(pkg_dir, target)
+ if built is None or built[0] in checked_in:
+ return None
+ base = _normalize_repo_rel(f"{pkg_dir}/src/{built[1].group(1)}")
+ return next((base + ext for ext in _BUILD_SOURCE_EXTENSIONS if base + ext in path_set), None)
+
+
+def manifest_entry_paths(
+ pkg_dir: str, pkg_data: dict, path_set: set[str], checked_in: frozenset[str] = frozenset()
+) -> set[str]:
+ """Files one ``package.json`` declares as where it starts.
+
+ Every ``bin`` target (string or map), ``main`` and ``module``, and the
+ first ``exports["."]`` target that resolves. Declaration files are skipped.
+ """
+ starts, exports = _manifest_targets(pkg_data)
+ found = {
+ hit
+ for t in starts
+ if (hit := probe_manifest_target(pkg_dir, t, path_set, checked_in)) is not None
+ }
+ for target in exports:
+ hit = probe_manifest_target(pkg_dir, target, path_set, checked_in)
+ if hit is not None:
+ found.add(hit)
+ break
+ return found
+
+
def build_ts_workspace_index(ctx: ResolverContext) -> TsWorkspaceIndex:
"""Build the workspace index for *ctx*.
@@ -749,7 +908,14 @@ def build_ts_workspace_index(ctx: ResolverContext) -> TsWorkspaceIndex:
resolved = _probe_path(f"{dir_posix}/{main.lstrip('./')}", path_set)
if resolved is not None:
entries.add(resolved)
- return TsWorkspaceIndex(packages=packages, exports_entry_paths=entries)
+ manifests = _parsed_package_jsons(ctx)
+ checked_in = checked_in_builds(ctx.repo_path, manifests, path_set)
+ declared: set[str] = set()
+ for pkg_dir, data in manifests:
+ declared |= manifest_entry_paths(pkg_dir, data, path_set, checked_in)
+ return TsWorkspaceIndex(
+ packages=packages, exports_entry_paths=entries, manifest_entry_paths=declared
+ )
def get_or_build_ts_index(ctx: ResolverContext) -> TsWorkspaceIndex:
@@ -975,10 +1141,6 @@ def find_npm_script_entry_targets(ctx: ResolverContext) -> set[str]:
if ctx.repo_path is None:
return set()
- # NOTE: not .resolve()d — the shared scan walks ctx.repo_path as given,
- # so relative_to() below must use the same base or it silently drops
- # every manifest.
- repo_root = ctx.repo_path
path_set = ctx.path_set
targets: set[str] = set()
@@ -994,20 +1156,10 @@ def find_npm_script_entry_targets(ctx: ResolverContext) -> set[str]:
dirs_in_repo.setdefault(p[:slash], []).append(p)
idx = slash + 1
- for pkg_file in _get_repo_scan(ctx).package_jsons:
- # node_modules manifests are already pruned by the shared scan.
- try:
- data = json.loads(pkg_file.read_text(encoding="utf-8", errors="ignore"))
- except Exception:
- continue
+ for pkg_rel, data in _parsed_package_jsons(ctx):
scripts = data.get("scripts") or {}
if not isinstance(scripts, dict):
continue
- pkg_dir = pkg_file.parent
- try:
- pkg_rel = pkg_dir.relative_to(repo_root).as_posix()
- except ValueError:
- continue
pkg_prefix = "" if pkg_rel in ("", ".") else f"{pkg_rel}/"
# Experimental sub-package convention: ``packages/bench``,
@@ -1019,7 +1171,7 @@ def find_npm_script_entry_targets(ctx: ResolverContext) -> set[str]:
# maintained script bag" signal — mark every source file under
# it as an entry. Honour ``"private": true`` *or* the directory
# name match; the conventional names are the load-bearing signal.
- pkg_dir_name = pkg_dir.name.lower()
+ pkg_dir_name = posixpath.basename(pkg_rel).lower()
if pkg_dir_name in _EXPERIMENT_DIR_NAMES:
dir_files = dirs_in_repo.get(pkg_rel) if pkg_rel else None
if dir_files:
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index 01a151324..e041dcb83 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -457,6 +457,10 @@ class FileTraverser:
def _distributions(self) -> frozenset[str]:
return self._console_script_tables().distributions
+ @property
+ def _distribution_inits(self) -> frozenset[str]:
+ return self._console_script_tables().package_inits
+
# ------------------------------------------------------------------
# Public API
# ------------------------------------------------------------------
@@ -785,6 +789,10 @@ class FileTraverser:
if language is None or self._skip_generated(abs_path, rel_str, language):
return None
+ manifest_entry = (
+ _is_console_script_target(rel_str, self._console_script_modules)
+ or rel_str in self._distribution_inits
+ )
return FileInfo(
path=rel_str,
abs_path=str(abs_path),
@@ -795,9 +803,8 @@ class FileTraverser:
is_test=is_test_related_path(rel_str, language),
is_config=_is_config_file(language),
is_api_contract=_is_api_contract(abs_path, language),
- is_entry_point=_is_entry_point(
- rel_str, abs_path, language, self._console_script_modules
- ),
+ is_entry_point=_is_entry_point(rel_str, abs_path, language) or manifest_entry,
+ is_manifest_entry=manifest_entry,
)
# ------------------------------------------------------------------
@@ -1115,18 +1122,14 @@ def _stem_is_entry_point(abs_path: Path) -> bool:
return stem in _ENTRY_POINT_STEMS
-def _is_entry_point(
- rel_str: str,
- abs_path: Path,
- language: str,
- console_script_modules: frozenset[str],
-) -> bool:
- """Whether this file gets ``FileInfo.is_entry_point``.
+def _is_entry_point(rel_str: str, abs_path: Path, language: str) -> bool:
+ """Whether this file's *name* earns ``FileInfo.is_entry_point``.
A conventional filename or stem is a guess, so it passes through
``not_an_execution_start``, the same correction the wiki's orientation list
- uses. A ``[project.scripts]`` target is named evidence, so it is checked
- outside that gate: this flag is what exempts a file from dead-code detection.
+ uses. A manifest-named file (a ``[project.scripts]`` target) is evidence,
+ so the caller ORs it in outside that gate: this flag is what exempts a
+ file from dead-code detection.
"""
filename = abs_path.name
named_entry = (
@@ -1134,9 +1137,7 @@ def _is_entry_point(
or filename.endswith(_ENTRY_POINT_NAME_SUFFIXES)
or _stem_is_entry_point(abs_path)
)
- if named_entry and not not_an_execution_start(rel_str, language):
- return True
- return _is_console_script_target(rel_str, console_script_modules)
+ return named_entry and not not_an_execution_start(rel_str, language)
class ConsoleScriptTables(NamedTuple):
@@ -1148,6 +1149,8 @@ class ConsoleScriptTables(NamedTuple):
"""Dotted module targets, used for entry-point detection."""
distributions: frozenset[str]
"""``[project].name`` values — the distributions this repo installs as."""
+ package_inits: frozenset[str]
+ """Repo-relative ``__init__.py`` of each distribution's own import package."""
def _collect_console_scripts(
@@ -1166,12 +1169,13 @@ def _collect_console_scripts(
names: set[str] = set()
modules: set[str] = set()
distributions: set[str] = set()
+ inits: set[str] = set()
try:
config_files = list(
iter_glob(repo_root, ("pyproject.toml",), prune_nested_git=prune_nested_git)
)
except OSError:
- return ConsoleScriptTables(frozenset(), frozenset(), frozenset())
+ return ConsoleScriptTables(frozenset(), frozenset(), frozenset(), frozenset())
for config_file in config_files:
project = _pyproject_project_table(config_file)
if project is None:
@@ -1179,8 +1183,27 @@ def _collect_console_scripts(
dist = project.get("name")
if isinstance(dist, str) and dist.strip():
distributions.add(dist.strip())
+ if (init := _distribution_init(repo_root, config_file.parent, dist)) is not None:
+ inits.add(init)
_add_script_targets(project, names, modules)
- return ConsoleScriptTables(frozenset(names), frozenset(modules), frozenset(distributions))
+ return ConsoleScriptTables(
+ frozenset(names), frozenset(modules), frozenset(distributions), frozenset(inits)
+ )
+
+
+def _distribution_init(repo_root: Path, base: Path, dist: str) -> str | None:
+ """The distribution's import package ``__init__.py``, flat or ``src/`` layout.
+
+ Ceiling: the import name is the normalised distribution name, so a package
+ that installs under another name (``[tool.setuptools] packages``, hatch
+ ``packages``) is not found; reading those tables is the upgrade path.
+ """
+ name = re.sub(r"[-.]+", "_", dist.strip()).lower()
+ inits = (base / name / "__init__.py", base / "src" / name / "__init__.py")
+ init = next((path for path in inits if path.is_file()), None)
+ if init is None or not init.is_relative_to(repo_root):
+ return None
+ return init.relative_to(repo_root).as_posix()
def _pyproject_project_table(config_file: Path) -> dict | None:
diff --git a/tests/unit/generation/test_entry_points.py b/tests/unit/generation/test_entry_points.py
index e0e16d687..7937a2391 100644
--- a/tests/unit/generation/test_entry_points.py
+++ b/tests/unit/generation/test_entry_points.py
@@ -4,6 +4,7 @@ from __future__ import annotations
from repowise.core.entry_candidacy import (
GLUE_STEMS,
+ conventional_entry_stems,
entry_point_depth,
is_glue_leaf,
not_an_execution_start,
@@ -131,3 +132,42 @@ def test_rank_key_orders_bucket_then_depth_then_centrality():
conv = entry_point_rank_key("a/app.py", pagerank=0.0, conventional_stems=_CONV)
glue = entry_point_rank_key("a/index.py", pagerank=1.0, conventional_stems=_CONV)
assert conv < glue # conventional name beats central glue regardless
+
+
+def test_manifest_tier_outranks_stem():
+ # A package.json ``bin`` target named ``run-it.ts`` five levels deep beats
+ # a shallow, highly central ``main.py`` and a shallow ``cli.ts`` guess.
+ declared = "packages/tool/src/commands/bin/run-it.ts"
+ candidates = [
+ ("main.py", 0.9, 0.9),
+ ("cli.ts", 0.5, 0.5),
+ (declared, 0.0, 0.0),
+ ]
+ ranked = rank_entry_points(candidates, _CONV, frozenset({declared}))
+ assert ranked[0] == declared
+ assert ranked[1:] == ["main.py", "cli.ts"]
+ # Within the tier the usual rules apply: a declared glue ``index`` sorts
+ # after a declared conventional name.
+ both = frozenset({"pkg/src/index.ts", "pkg/src/cli.ts"})
+ ranked = rank_entry_points(
+ [("pkg/src/index.ts", 0.9, 0.9), ("pkg/src/cli.ts", 0.0, 0.0), ("main.py", 0.0, 0.0)],
+ _CONV,
+ both,
+ )
+ assert ranked == ["pkg/src/cli.ts", "pkg/src/index.ts", "main.py"]
+
+
+def test_entry_stem_not_conventional():
+ # ``entry`` names a keyring's ``class Entry`` as often as a front door: it
+ # ranks neutral. ``run`` is a flag stem (dead-code exempt), never a
+ # ranking stem. Both keep the traverser flag.
+ from repowise.core.ingestion.traverser import _ENTRY_POINT_STEMS
+
+ assert "entry" not in conventional_entry_stems()
+ assert "run" not in conventional_entry_stems()
+ assert {"entry", "run"} <= _ENTRY_POINT_STEMS
+ stems = conventional_entry_stems()
+ ranked = rank_entry_points([("src/entry.ts", 0.9, 0.9), ("src/main.ts", 0.0, 0.0)], stems)
+ assert ranked == ["src/main.ts", "src/entry.ts"]
+ key = entry_point_rank_key("src/entry.ts", conventional_stems=stems)
+ assert key[1] == 1 # neutral name bucket
diff --git a/tests/unit/ingestion/test_language_capabilities.py b/tests/unit/ingestion/test_language_capabilities.py
index c8886034b..e5fc9ef22 100644
--- a/tests/unit/ingestion/test_language_capabilities.py
+++ b/tests/unit/ingestion/test_language_capabilities.py
@@ -44,7 +44,6 @@ class TestParityGoldens:
"cli",
"__main__",
"bootstrap",
- "entry",
}
) == _ENTRY_FILENAME_STEMS
@@ -337,7 +336,8 @@ class TestDriftManifests:
# hard-coded frozenset (run.py/server.py extras were redundant with the
# run/server stems). The traverser now flags on this *unioned* with
# conventional_entry_stems(); that union is pinned in
- # tests/unit/generation/test_entry_points.py.
+ # tests/unit/generation/test_entry_points.py. ``entry`` moved here from
+ # the ranking stems, so the union (the traverser's flag) is unchanged.
assert REGISTRY.entry_flag_stems() == frozenset(
- {"main", "index", "app", "run", "server", "start", "wsgi", "asgi"}
+ {"main", "index", "app", "run", "server", "start", "entry", "wsgi", "asgi"}
)
diff --git a/tests/unit/ingestion/test_manifest_entry_points.py b/tests/unit/ingestion/test_manifest_entry_points.py
new file mode 100644
index 000000000..a98ac354f
--- /dev/null
+++ b/tests/unit/ingestion/test_manifest_entry_points.py
@@ -0,0 +1,248 @@
+"""Manifest-declared entry points (tier 0), end to end.
+
+Each fixture is a small repo on disk driven through the real traverser, parser,
+GraphBuilder (whose warmups stamp the TS manifest entries) and KG curation, so
+the three places the answer lands are checked together: ``FileInfo`` (what the
+entry-point list ranks), the graph node (what dead code reads) and
+``project.entry_points`` (what the overview shows).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.analysis.kg_curation import curate_knowledge_graph
+from repowise.core.analysis.knowledge_graph import build_knowledge_graph_skeleton
+from repowise.core.ingestion.graph import GraphBuilder
+from repowise.core.ingestion.parser import ASTParser
+from repowise.core.ingestion.resolvers.ts_workspace import (
+ checked_in_builds,
+ manifest_entry_paths,
+)
+from repowise.core.ingestion.traverser import FileTraverser
+
+_PARSER = ASTParser()
+
+
+def _write(repo: Path, files: dict[str, str]) -> Path:
+ for rel, body in files.items():
+ path = repo / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(body, encoding="utf-8")
+ return repo
+
+
+def _index(repo: Path) -> SimpleNamespace:
+ traverser = FileTraverser(repo)
+ infos = list(traverser.traverse())
+ parser = _PARSER
+ builder = GraphBuilder(repo)
+ parsed = []
+ for fi in infos:
+ pf = parser.parse_file(fi, Path(fi.abs_path).read_bytes())
+ builder.add_file(pf)
+ parsed.append(pf)
+ graph = builder.build()
+ structure = traverser.get_repo_structure(infos)
+ skeleton = build_knowledge_graph_skeleton(
+ parsed_files=parsed,
+ graph_builder=builder,
+ repo_structure=structure,
+ tech_stack=[],
+ external_systems=[],
+ )
+ kg = curate_knowledge_graph(
+ skeleton,
+ parsed_files=parsed,
+ graph_builder=builder,
+ repo_structure=structure,
+ community_info=builder.community_info(),
+ enabled=True,
+ )
+ return SimpleNamespace(
+ info={pf.file_info.path: pf.file_info for pf in parsed},
+ graph=graph,
+ project=kg.project,
+ )
+
+
+def _declared(idx: SimpleNamespace) -> set[str]:
+ return {p for p, fi in idx.info.items() if fi.is_manifest_entry}
+
+
+def pnpm_bin_dist_to_src(tmp_path: Path) -> Path:
+ """A pnpm package publishing a built CLI; only its sources are checked in."""
+ return _write(
+ tmp_path,
+ {
+ "pnpm-workspace.yaml": "packages:\n - 'packages/**'\n",
+ "package.json": json.dumps({"name": "root", "private": True}),
+ "packages/tools/cli/package.json": json.dumps(
+ {
+ "name": "@acme/cli",
+ "bin": {"acme": "./dist/cli.js", "acme-dev": "./dist/dev.mjs"},
+ "main": "./dist/index.js",
+ }
+ ),
+ "packages/tools/cli/src/cli.ts": "import { run } from './index';\nrun();\n",
+ "packages/tools/cli/src/dev.ts": "import { run } from './index';\nrun();\n",
+ "packages/tools/cli/src/index.ts": "export function run() {}\n",
+ "packages/keyring/src/entry.ts": "export class Entry {}\n",
+ "harness/run.mjs": "console.log('bench');\n",
+ },
+ )
+
+
+def test_pnpm_bin_dist_to_src(pnpm_bin_dist_to_src: Path) -> None:
+ idx = _index(pnpm_bin_dist_to_src)
+ declared = {
+ "packages/tools/cli/src/cli.ts",
+ "packages/tools/cli/src/dev.ts",
+ "packages/tools/cli/src/index.ts",
+ }
+ assert _declared(idx) == declared
+ for path in declared:
+ assert idx.info[path].is_entry_point
+ assert idx.graph.nodes[path]["is_entry_point"]
+ # Declared entries lead, the deep glue ``index.ts`` included; the stem
+ # guesses (``run.mjs``, a keyring ``entry.ts``) follow.
+ assert set(idx.project["entry_points"][:3]) == declared
+ assert idx.project["entry_points"][2] == "packages/tools/cli/src/index.ts"
+ assert "harness/run.mjs" in idx.project["entry_points"][3:]
+
+
+def test_npm_exports_only_dist(tmp_path: Path) -> None:
+ """``exports["."]`` pointing at build output only; ``types`` is skipped."""
+ repo = _write(
+ tmp_path,
+ {
+ "package.json": json.dumps(
+ {
+ "name": "lib",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.mjs",
+ "require": "./dist/index.cjs",
+ },
+ "./utils": "./dist/utils.mjs",
+ },
+ }
+ ),
+ "src/index.ts": "export * from './utils';\n",
+ "src/utils.ts": "export const u = 1;\n",
+ },
+ )
+ idx = _index(repo)
+ # Only "." is where the package starts; a subpath export is not.
+ assert _declared(idx) == {"src/index.ts"}
+ assert idx.project["entry_points"][0] == "src/index.ts"
+
+
+def test_exports_conditions_object_is_the_root_export() -> None:
+ data = {"exports": {"import": "./build/main.mjs", "types": "./build/main.d.ts"}}
+ assert manifest_entry_paths(".", data, {"src/main.ts"}) == {"src/main.ts"}
+
+
+def test_pyproject_scripts_and_dist_init(tmp_path: Path) -> None:
+ repo = _write(
+ tmp_path,
+ {
+ "pyproject.toml": (
+ '[project]\nname = "my-tool"\n[project.scripts]\nmytool = "my_tool.cli:main"\n'
+ ),
+ "src/my_tool/__init__.py": "from .core import thing\n",
+ "src/my_tool/cli.py": "def main():\n pass\n",
+ "src/my_tool/core.py": "def thing():\n pass\n",
+ "run.py": "print('x')\n",
+ },
+ )
+ idx = _index(repo)
+ assert _declared(idx) == {"src/my_tool/cli.py", "src/my_tool/__init__.py"}
+ assert idx.graph.nodes["src/my_tool/__init__.py"]["is_entry_point"]
+ assert idx.project["entry_points"][:2] == ["src/my_tool/cli.py", "src/my_tool/__init__.py"]
+ # ``run.py`` keeps its flag (dead-code exemption) but ranks after both.
+ assert idx.info["run.py"].is_entry_point
+ assert idx.project["entry_points"].index("run.py") == 2
+
+
+def test_committed_dist_no_remap(tmp_path: Path) -> None:
+ """A checked-in build is the entry itself, so the source is not named."""
+ repo = _write(
+ tmp_path,
+ {
+ "package.json": json.dumps({"name": "shipped", "main": "./dist/index.js"}),
+ "dist/index.js": "module.exports = {};\n",
+ "src/index.ts": "export {};\n",
+ },
+ )
+ idx = _index(repo)
+ assert _declared(idx) == set()
+
+
[email protected](shutil.which("git") is None, reason="needs git")
+def test_gitignored_build_is_remapped(tmp_path: Path) -> None:
+ """A local, gitignored build is not the checkout: map it to its source.
+
+ One batched check answers for every package: the sibling package's
+ committed ``lib`` build still counts as checked in.
+ """
+ repo = _write(
+ tmp_path,
+ {
+ ".gitignore": "dist/\n",
+ "a/package.json": "{}",
+ "a/dist/index.js": "module.exports = {};\n",
+ "a/src/index.ts": "export {};\n",
+ "b/lib/main.js": "module.exports = {};\n",
+ "b/src/main.ts": "export {};\n",
+ },
+ )
+ subprocess.run(["git", "init", "-q", str(repo)], check=True)
+ manifests = [("a", {"main": "./dist/index.js"}), ("b", {"main": "./lib/main.js"})]
+ path_set = {"a/src/index.ts", "b/src/main.ts"}
+ checked_in = checked_in_builds(repo, manifests, path_set)
+ assert checked_in == {"b/lib/main.js"}
+ assert manifest_entry_paths("a", manifests[0][1], path_set, checked_in) == {"a/src/index.ts"}
+ assert manifest_entry_paths("b", manifests[1][1], path_set, checked_in) == set()
+
+
+def test_build_target_escaping_the_repo_is_ignored(tmp_path: Path) -> None:
+ (tmp_path / "outside.js").write_text("x", encoding="utf-8")
+ repo = _write(tmp_path / "repo", {"src/x.ts": "export {};\n"})
+ manifests = [(".", {"main": "dist/../../outside.js"})]
+ assert checked_in_builds(repo, manifests, {"src/x.ts"}) == frozenset()
+ assert manifest_entry_paths(".", manifests[0][1], {"src/x.ts"}) == set()
+
+
+def test_fixture_pkg_under_tests(tmp_path: Path) -> None:
+ """Test and example packages' bins stay dead-code exempt but are never surfaced."""
+ repo = _write(
+ tmp_path,
+ {
+ "tests/e2e/pkg/package.json": json.dumps({"name": "fx", "bin": "./tool.js"}),
+ "tests/e2e/pkg/tool.js": "console.log(1);\n",
+ "examples/demo/package.json": json.dumps({"name": "demo", "main": "./start.js"}),
+ "examples/demo/start.js": "console.log(1);\n",
+ "src/main.py": "print('x')\n",
+ },
+ )
+ idx = _index(repo)
+ for hidden in ("tests/e2e/pkg/tool.js", "examples/demo/start.js"):
+ assert idx.info[hidden].is_manifest_entry
+ assert idx.graph.nodes[hidden]["is_entry_point"]
+ assert hidden not in idx.project["entry_candidates"]
+ assert idx.project["entry_points"] == ["src/main.py"]
+
+
+def test_committed_declaration_target_is_not_an_entry() -> None:
+ data = {"main": "./types/index.d.ts", "bin": "./types/cli.d.cts"}
+ path_set = {"types/index.d.ts", "types/cli.d.cts"}
+ assert manifest_entry_paths(".", data, path_set) == set()