Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(ingestion): HTML at the import tier via script src and link href (#1235)
Raghav Chamadiya3ee0f0741844
diff --git a/README.md b/README.mdindex ddedf3dbe..4eef349bd 100644--- a/README.md+++ b/README.md@@ -368,9 +368,10 @@ Set Up This Repository**. Guide: **[docs/agent/VSCODE.md →](docs/agent/VSCODE.</p>SQL and dbt projects get real `ref()` / `source()` lineage, shell scripts get-function-level symbols, and OpenAPI, Protobuf, GraphQL, Dockerfile, Terraform and-friends get dedicated handlers. Anything else is still tracked through git history:-blame, hotspots, co-change.+function-level symbols, HTML pages contribute their `<script src>` / `<link href>`+dependencies (including `index.html` → `src/main.ts`), and OpenAPI, Protobuf,+GraphQL, Dockerfile, Terraform and friends get dedicated handlers. Anything else is+still tracked through git history: blame, hotspots, co-change.Adding a language takes **one `.scm` query file and one config entry**, with no changesto the parser core. Full matrix and the contributor recipe:diff --git a/docs/architecture/language-support.md b/docs/architecture/language-support.mdindex 4271160cb..62499ea9e 100644--- a/docs/architecture/language-support.md+++ b/docs/architecture/language-support.md@@ -322,7 +322,19 @@ a `Locator`, not a second copy of the walker.There is no `tree-sitter-vue` on PyPI. The HTML grammar parses a Vue SFCcleanly anyway, because `<template>`, `<script>` and `<style>` are ordinary-elements to it — so one dependency covers Vue and, later, plain HTML.+elements to it — so one dependency covers both Vue and plain HTML.++**Plain HTML deliberately has no locator.** It reuses the same grammar but not+the projection, and the distinction is the point: a projection exists to turn a+`<script>` block into analysable TypeScript, which is worth it when that block+is where the component lives. A plain `.html` file's inline script almost never+carries a module import — 13 of the 6162 `.html` files in the validation corpus+(0.2%) — so projecting would buy a rounding error and would mint symbols,+contradicting HTML's import-only tier. Its `<script src>` / `<link href>`+attributes are read directly in+`lightweight_imports/html.py`, which is extractor work, not projection work.+Adding a `Locator` for HTML purely for symmetry with Vue and Svelte would be a+mistake; `_LOCATORS` is for languages whose *script blocks* need projecting.Vue's expressions live in attribute *values*, which is why the fence bytes arequotes rather than braces, and why only directive attributes (`:`, `@`, `v-`)diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.mdindex 4b53cba72..4377123ec 100644--- a/docs/business/COMMERCIAL.md+++ b/docs/business/COMMERCIAL.md@@ -82,13 +82,13 @@ All of the following ship in `pip install repowise` today, free for internal use## 3. First-class language coverage-Repowise treats **12 languages at Full tier** (Python, TypeScript, JavaScript, Svelte, Java,-Kotlin, Go, Rust, C++, **C#**, Scala, and Ruby) with AST parsing, import resolution,-named bindings, call resolution, heritage extraction, multi-project workspace-resolvers, framework-aware edges, per-language dynamic-hint extractors, and+Repowise treats **13 languages at Full tier** (Python, TypeScript, JavaScript, Svelte,+Vue, Java, Kotlin, Go, Rust, C++, **C#**, Scala, and Ruby) with AST parsing, import+resolution, named bindings, call resolution, heritage extraction, multi-project+workspace resolvers, framework-aware edges, per-language dynamic-hint extractors, andcode-health markers. A further 4 languages (C, Swift, PHP, Dart) sit at Good tier,-and Luau is partial. SQL/dbt, shell, and the config formats are handled by dedicated-extractors on top of that.+and Luau is partial. SQL/dbt, shell, HTML, and the config formats are handled by+dedicated extractors on top of that.For estates built on a particular stack, the relevant Full-tier capabilities areworth calling out. For **.NET**, as one example:diff --git a/docs/layers/LANGUAGE_SUPPORT.md b/docs/layers/LANGUAGE_SUPPORT.mdindex 253f9da3b..27f82890e 100644--- a/docs/layers/LANGUAGE_SUPPORT.md+++ b/docs/layers/LANGUAGE_SUPPORT.md@@ -24,7 +24,7 @@ produce meaningful output.| **SQL / dbt** | `.sql` via sqlglot | Tables / views / functions / procedures as symbols with wiki pages; dbt projects get real `ref()` / `source()` lineage || **Shell** | `.sh` `.bash` `.zsh` | Function definitions as symbols, `source` / `.` import edges (incl. `$SCRIPT_DIR` / `dirname` / `$BATS_ROOT` idioms), and function-level code-health complexity (CCN, nesting, cognitive). No class metrics, heritage, bindings, or dead-code flagging || **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · Terraform · Markdown | In the file tree and wiki; special handlers extract endpoints / targets where applicable |-| **Lightweight** | Elixir · Clojure · Haskell · Lean 4 · Erlang · F# | Regex-tier file-level import graph (no symbols/calls). Honest file-to-file dependencies, no symbol-level claims |+| **Lightweight** | Elixir · Clojure · Haskell · Lean 4 · Erlang · F# · HTML | File-level import graph only (no symbols/calls). Honest file-to-file dependencies, no symbol-level claims || **Partial** | Luau / Roblox | AST symbols + `require()` resolution (Rojo / `.luaurc` aware); no health markers yet || **Structural** | Objective-C · R · Zig · Julia · Elm · OCaml · Crystal · Nim · D | Git history only (blame, hotspots, co-change). No AST parsing |@@ -34,7 +34,7 @@ produce meaningful output.|-------|:----:|:----:|:-----------:|:----------:|:-------------:|| File discovery & git history | ✅ | ✅ | ✅ | ✅ | ✅ || AST symbol extraction | ✅ | ✅ | - | - | - |-| Import resolution | ✅¹ | ✅ | regex | - | - |+| Import resolution | ✅¹ | ✅ | file-level³ | - | - || Call graph edges | ✅ | ✅ | - | - | - || Heritage (extends/implements) | ✅ | ✅ | - | - | - || Named bindings | ✅ | ✅ | - | - | - |@@ -47,6 +47,10 @@ build-file fallback); every other Full and Good language resolves importsfully.² See [code-health coverage](#code-health-coverage), a language is only "Full"once it clears the health checklist.+³ File-to-file only, no symbol resolution. Regex-extracted for every+Lightweight language except HTML, which uses the `tree-sitter-html` grammar.+Dead-code detection covers the Lightweight tier except HTML, which is never+flagged (see below).---@@ -191,12 +195,38 @@ rather than tree-sitter, plus the lightweight import tier for dbt lineage.## Lightweight, Partial, and Structural tiers-**Lightweight** (Elixir, Clojure, Haskell, Lean 4, Erlang, F#), no AST parsing,-but a real file-level import graph from a regex tier: import statements are-extracted per-language and resolved against a declared module-name index. The-knowledge graph runs in flow/sparse mode on the result: honest file-to-file-dependencies, no symbol-level claims. F# additionally honours the fsproj-`<Compile Include>` compile-order spine.+**Lightweight** (Elixir, Clojure, Haskell, Lean 4, Erlang, F#, HTML), no symbol+extraction, but a real file-level import graph: import statements are extracted+per-language and resolved against a declared module-name index. The knowledge+graph runs in flow/sparse mode on the result: honest file-to-file dependencies,+no symbol-level claims. F# additionally honours the fsproj `<Compile Include>`+compile-order spine. All of these use a regex tier except HTML, which uses the+`tree-sitter-html` grammar repowise already ships for Vue.++**HTML** (`.html` / `.htm`) is import-tier *only*, and deliberately so: HTML has+no functions, classes or calls, so there are no symbols to claim. What it does+carry is `<script src>` and `<link href>`, which become file-level edges —+including the one every Vite/webpack SPA depends on, `index.html` →+`src/main.ts`. References are resolved as document- or root-relative asset+paths, never as module specifiers: there is no extension inference and no+`index.*` lookup, because `src="./app"` in a browser fetches a file literally+named `app`. A root-relative `/src/main.tsx` is anchored first at the+referencing page's own directory (the bundler convention), then at its+`public/`, then by unique path suffix; a tie yields no edge rather than a+guessed one. CDN and `data:` references are external and mint no edge.++`.html` files are **never flagged as dead code**. Whether a page is reachable+is not statically decidable — a server serves it, a human navigates to it, a+build copies it — and checked-in generated HTML is everywhere. Their outbound+edges still anchor everything they reference.++The known ceiling is **template dialects**. Django/Jinja, Go templates, ERB,+Handlebars, Blade, Thymeleaf and Angular's `*ngIf` are invisible to an HTML+parser: `{% extends "base.html" %}` is plain text, so such a file parses+cleanly and yields nothing. Measured on the validation corpus, 744 of 749+template-dialect files (99.3%) produce no edges at all. Covering them needs a+per-dialect regex tier gated on a framework manifest — a different mechanism,+not yet built.**Partial** (Luau / Roblox), AST symbols, Luau type aliases, and `require(...)`capture are wired. Import resolution handles string literals, `script` relative@@ -374,6 +404,7 @@ where a dialect isn't wired yet. Per-marker mechanics and precision hazards:| F# | Good | Lightweight tier shipped; AST upgrade planned (`tree-sitter-f-sharp` available) || SQL / dbt | - | DDL symbols, dbt lineage, app-to-database contracts, health markers shipped. Next: column-level blast radius || Shell | - | Function symbols, `source` import edges, function-level complexity shipped. Next: shebang-based detection of extensionless executables (a traverser capability) |+| HTML | Lightweight | Shipped: `<script src>` / `<link href>` edges with document-, `public/`- and root-relative resolution; never dead-code flagged. Stays import-tier — HTML has no symbols. Next: a regex import tier for template dialects (Django/Jinja, Go templates, ERB, Handlebars), gated on a framework manifest |---diff --git a/packages/core/src/repowise/core/ingestion/languages/specs/__init__.py b/packages/core/src/repowise/core/ingestion/languages/specs/__init__.pyindex 76bf55203..219416cde 100644--- a/packages/core/src/repowise/core/ingestion/languages/specs/__init__.py+++ b/packages/core/src/repowise/core/ingestion/languages/specs/__init__.py@@ -27,6 +27,7 @@ from .fsharp import SPEC as _FSHARPfrom .go import SPEC as _GOfrom .graphql import SPEC as _GRAPHQLfrom .haskell import SPEC as _HASKELL+from .html import SPEC as _HTMLfrom .java import SPEC as _JAVAfrom .javascript import SPEC as _JAVASCRIPTfrom .json import SPEC as _JSON@@ -106,6 +107,11 @@ ALL_SPECS: tuple[LanguageSpec, ...] = (_ASCIIDOC,_SQL,_OPENAPI,+ # HTML carries no symbols, but <script src>/<link href> are real file-level+ # edges — extracted on the no-grammar path and resolved as document- or+ # root-relative asset paths. Markup, so it is never reported as dead code+ # while its edges still anchor what it references.+ _HTML,# XAML / AXAML markup for WPF, WinUI 3, UWP, MAUI, Avalonia, Uno.# No AST grammar — handled by the XamlDynamicHints extractor which# emits ``dynamic_uses`` edges to bound C# types. Registered here sodiff --git a/packages/core/src/repowise/core/ingestion/languages/specs/html.py b/packages/core/src/repowise/core/ingestion/languages/specs/html.pynew file mode 100644index 000000000..3e9a59ab7--- /dev/null+++ b/packages/core/src/repowise/core/ingestion/languages/specs/html.py@@ -0,0 +1,59 @@+"""LanguageSpec for html — an import-tier language, deliberately.++HTML has no functions, classes or calls, so there is nothing for a symbol+extractor to find and no ``scm_file`` to point at. What it *does* carry is+file-level dependency edges: ``<script src>`` and ``<link href>``. Those are+attribute reads, so they are extracted by ``lightweight_imports/html.py`` and+resolved by ``resolvers/html.py``; the file lands on ``parse_file``'s+no-``LanguageConfig`` path, which yields an empty symbol list and real+``Import`` entries. That is the whole tier, and ``import_support="partial"``+says so.++No SFC projection. Vue and Svelte earn one because a ``<script>`` block is+where the component lives; a plain ``.html`` file's inline script almost never+carries a module import — 13 of the 6162 ``.html`` files in the validation+corpus (0.2%). Projecting for that would buy a rounding error and would mint+symbols, contradicting the import-only tier. So HTML registers no+``sfc_source`` locator and no synthetic component symbol.++``is_code=False`` is both truthful and load-bearing. HTML is markup, like+``xaml`` and ``markdown`` — and the classification puts it in dead code's+``_NON_CODE_LANGUAGES``, so an ``.html`` file is never *reported* as dead while+its outbound edges still anchor everything it references. That is the correct+semantics twice over: whether a page is reachable is not statically decidable+(a server serves it, a human navigates to it, a build copies it), and checked-in+generated HTML is everywhere — 4204 of the corpus's 6162 files are one+repository's committed Dokka API docs. Exempting the language structurally+beats chasing those with never-flag globs.++Known gap, and it is the big one: template dialects. Django/Jinja, Go+templates, ERB, Handlebars, Blade, Thymeleaf and Angular's ``*ngIf`` are+invisible to an HTML parser — ``{% extends "base.html" %}`` is plain text, so+such a file parses cleanly and yields nothing. That is 44% of the corpus once+the generated Dokka tree is set aside (843 of 1931 files). Covering it needs a+per-dialect regex tier gated on a framework manifest, which is a different+mechanism with its own precision questions.+"""++from ..spec import LanguageSpec++SPEC = LanguageSpec(+ tag="html",+ display_name="HTML",+ extensions=frozenset({".html", ".htm"}),+ # Markup, not code: no symbols exist to extract, and this is what makes the+ # language dead-code exempt. See the module docstring.+ is_code=False,+ is_passthrough=True,+ # A dedicated resolver for src/href with one major known gap (template+ # dialects). Not "full" — that would overclaim on 44% of real-world .html.+ import_support="partial",+ # The entry of every Vite/webpack/Parcel SPA: index.html is what references+ # src/main.ts, and nothing imports index.html in turn. Marking it an entry+ # point is what lets that edge anchor the app's reachability.+ entry_point_patterns=("index.html",),+ # Build output that is routinely committed. These carry no hand-written+ # dependency information and would only add noise to the graph.+ blocked_dirs=("node_modules", "dist", "build", "_site", ".next", "htmlcov"),+ color_hex="#E34F26",+)diff --git a/packages/core/src/repowise/core/ingestion/lightweight_imports/__init__.py b/packages/core/src/repowise/core/ingestion/lightweight_imports/__init__.pyindex ca1ebdca2..552806ade 100644--- a/packages/core/src/repowise/core/ingestion/lightweight_imports/__init__.py+++ b/packages/core/src/repowise/core/ingestion/lightweight_imports/__init__.py@@ -1,12 +1,18 @@-"""Regex-tier import extraction for languages without a tree-sitter grammar.+"""Import-only extraction for languages the symbol pipeline does not parse.Languages whose ``LanguageSpec.import_support`` is ``"partial"`` via the-lightweight-resolver mechanism get their import statements extracted here-with per-language regexes over the raw source text — no AST. The parser-consults :func:`extract_lightweight_imports` on its no-grammar path, so-these files keep an empty symbol list (the regex tier claims no symbol-knowledge) but carry real :class:`~..models.Import` entries that flow-through the standard resolver dispatch.+lightweight-resolver mechanism get their import statements extracted here.+The parser consults :func:`extract_lightweight_imports` on its+no-``LanguageConfig`` path, so these files keep an empty symbol list — this+tier claims no symbol knowledge — but carry real :class:`~..models.Import`+entries that flow through the standard resolver dispatch.++That empty-symbols contract, not the parsing technique, is what defines the+tier. Most members here have no tree-sitter grammar at all and match with+per-language regexes over the raw text. ``html`` is the exception: repowise+already ships ``tree-sitter-html`` for Vue, so its extractor uses the real+grammar. It stays here because what it produces is the same — imports, no+symbols."""from __future__ import annotations@@ -20,6 +26,7 @@ from .elixir import extract_elixir_importsfrom .erlang import extract_erlang_importsfrom .fsharp import extract_fsharp_importsfrom .haskell import extract_haskell_imports+from .html import extract_html_importsfrom .lean import extract_lean_importsfrom .sql import extract_dbt_imports@@ -36,6 +43,8 @@ _EXTRACTORS: dict[str, ExtractorFn] = {# dbt {{ ref() }} / {{ source() }}, the only import system .sql files# have; plain SQL contains neither form, so this is a no-op outside dbt."sql": extract_dbt_imports,+ # <script src> / <link href>. AST-backed rather than regex — see above.+ "html": extract_html_imports,}LIGHTWEIGHT_IMPORT_LANGUAGES = frozenset(_EXTRACTORS)diff --git a/packages/core/src/repowise/core/ingestion/lightweight_imports/html.py b/packages/core/src/repowise/core/ingestion/lightweight_imports/html.pynew file mode 100644index 000000000..052d0937c--- /dev/null+++ b/packages/core/src/repowise/core/ingestion/lightweight_imports/html.py@@ -0,0 +1,135 @@+"""``<script src>`` / ``<link href>`` extraction for plain HTML.++These two attributes are the only import system HTML has, and they are+file-level: a page depends on a script or a stylesheet, never on a symbol+inside one. So this yields ``Import`` entries and no symbols, which is exactly+what the no-``LanguageConfig`` path in ``parse_file`` expects.++Unlike its sibling modules this one is not a regex. ``tree-sitter-html`` is+already a dependency — Vue's locator in ``sfc_source`` uses it — so the real+grammar is free here, and it reads unquoted (``src=app.js``) and multi-line+tags that an attribute regex gets wrong. It also knows what a comment is,+though that mattered less than expected: exactly 1 of 777 local references in+the validation corpus sat inside one.++Only ``<script src>`` and ``<link href>`` are captured. ``<a href>`` is+navigation between pages rather than a dependency, and ``<img src>`` is an+asset with no code in it; minting edges for either would inflate the graph+without saying anything about how the code fits together.++Template dialects are the known ceiling. ``{% extends "base.html" %}``,+``{{ template "x" }}`` and ``<%= render %>`` are ordinary text to an HTML+grammar, so a Django or Hugo template parses cleanly and yields nothing here.+That is a property of the tier, not a bug in it — see the ``html`` spec.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from ..models import Import++if TYPE_CHECKING:+ from tree_sitter import Node++# tag name -> the attribute on it that names a dependency.+_REF_ATTRS: dict[str, str] = {"script": "src", "link": "href"}++# A reference that leaves the repository: protocol-relative (//cdn...),+# absolute URLs, inline data, in-page anchors, and the non-fetching schemes.+_EXTERNAL_PREFIXES = ("//", "http://", "https://", "data:", "#", "mailto:", "javascript:")+++def _attributes(start_tag: Node) -> dict[str, str]:+ """Map attribute name (lowercased) to value for one start tag.++ Handles both quoted and bare values: tree-sitter-html nests the former in a+ ``quoted_attribute_value`` wrapper and leaves the latter as a direct+ ``attribute_value`` child.+ """+ attrs: dict[str, str] = {}+ for attr in start_tag.children:+ if attr.type != "attribute":+ continue+ name = value = None+ for child in attr.children:+ if child.type == "attribute_name":+ name = child.text+ elif child.type == "attribute_value":+ value = child.text+ elif child.type == "quoted_attribute_value":+ inner = next((c for c in child.children if c.type == "attribute_value"), None)+ # An empty value ("") has no inner node at all.+ value = inner.text if inner is not None else b""+ if name is not None and value is not None:+ attrs[name.decode("utf-8", "replace").lower()] = value.decode("utf-8", "replace")+ return attrs+++def _start_tag(node: Node) -> Node | None:+ return next((c for c in node.children if c.type == "start_tag"), None)+++def _walk(node: Node, out: list[tuple[str, str]]) -> None:+ # <script> gets its own node type; <link> is a plain element.+ if node.type in ("script_element", "element"):+ start = _start_tag(node)+ if start is not None:+ name_node = next((c for c in start.children if c.type == "tag_name"), None)+ if name_node is not None and name_node.text is not None:+ tag = name_node.text.decode("utf-8", "replace").lower()+ attr = _REF_ATTRS.get(tag)+ if attr is not None:+ value = _attributes(start).get(attr, "").strip()+ if value:+ out.append((tag, value))+ for child in node.children:+ _walk(child, out)+++def extract_html_imports(text: str) -> list[Import]:+ """Return one ``Import`` per local ``<script src>`` / ``<link href>``."""+ from ..sfc_source import _grammar++ grammar = _grammar("tree_sitter_html")+ if grammar is None:+ return []++ try:+ from tree_sitter import Parser++ tree = Parser(grammar).parse(text.encode("utf-8"))+ except Exception:+ # A file we cannot parse contributes no edges rather than wrong ones.+ return []++ refs: list[tuple[str, str]] = []+ _walk(tree.root_node, refs)++ imports: list[Import] = []+ seen: set[str] = set()+ for tag, value in refs:+ # An external reference is dropped here rather than passed to the+ # resolver: it names a CDN, not a file in this repository, and the+ # resolver's job is repo-relative paths.+ if value.startswith(_EXTERNAL_PREFIXES):+ continue+ # A dialect left its own syntax in the attribute ({{ url_for(...) }},+ # {% static %}, <%= asset_path %>) — not a static path.+ if any(sigil in value for sigil in ("{{", "{%", "<%", "${")):+ continue+ if value in seen:+ continue+ seen.add(value)+ imports.append(+ Import(+ raw_statement=f'<{tag} {_REF_ATTRS[tag]}="{value}">',+ module_path=value,+ imported_names=[],+ # Root-relative (/static/app.js) is resolved against the repo+ # root, not the importing document, so it is not "relative".+ is_relative=not value.startswith("/"),+ resolved_file=None,+ )+ )+ return importsdiff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.pyindex 591bcf5d8..5a1596d5f 100644--- a/packages/core/src/repowise/core/ingestion/models.py+++ b/packages/core/src/repowise/core/ingestion/models.py@@ -71,6 +71,8 @@ LanguageTag = Literal["sql","openapi","xaml",+ # Markup with no symbols, but <script src>/<link href> are real edges.+ "html","unknown",]diff --git a/packages/core/src/repowise/core/ingestion/resolvers/__init__.py b/packages/core/src/repowise/core/ingestion/resolvers/__init__.pyindex 0046fa015..989ba97a2 100644--- a/packages/core/src/repowise/core/ingestion/resolvers/__init__.py+++ b/packages/core/src/repowise/core/ingestion/resolvers/__init__.py@@ -15,6 +15,7 @@ from .fsharp import resolve_fsharp_importfrom .generic import resolve_generic_importfrom .go import resolve_go_importfrom .haskell import resolve_haskell_import+from .html import resolve_html_assetfrom .java import resolve_java_importfrom .kotlin import resolve_kotlin_importfrom .lean import resolve_lean_import@@ -63,6 +64,9 @@ _RESOLVERS: dict[str, ResolverFn] = {"fsharp": resolve_fsharp_import,# dbt ref()/source(), gated on dbt_project.yml via the model index."sql": resolve_dbt_import,+ # <script src>/<link href> are asset paths, not module specifiers — they+ # get their own document-/root-relative resolution, never the TS/JS one.+ "html": resolve_html_asset,}diff --git a/packages/core/src/repowise/core/ingestion/resolvers/html.py b/packages/core/src/repowise/core/ingestion/resolvers/html.pynew file mode 100644index 000000000..d38f333ef--- /dev/null+++ b/packages/core/src/repowise/core/ingestion/resolvers/html.py@@ -0,0 +1,113 @@+"""``<script src>`` / ``<link href>`` resolution.++An HTML reference is a *path*, not a module specifier, so this deliberately+does not go through ``resolve_ts_js_import``: there is no extension inference,+no ``index.*`` lookup, no ``node_modules`` walk and no tsconfig alias. Writing+``src="./app"`` in HTML fetches a file literally named ``app``; only+``src="./app.js"`` loads the script. Borrowing the TS/JS resolver would invent+edges the browser would never follow.++Two forms reach here, and they anchor differently:++1. **Document-relative** — ``app.js``, ``./js/app.js``, ``../shared/x.css``.+ Resolved against the directory of the referencing page, like any relative+ path.+2. **Root-relative** — ``/src/main.tsx``, ``/static/js/app.js``. The leading+ ``/`` is the *web* root, which is almost never the repository root: Flask+ serves ``static/`` from ``app/static/``, Django collects from+ ``<app>/static/``, and Vite treats the directory holding ``index.html`` as+ the project root. Two anchors are tried, in order:++ a. The referencing page's own directory. This is the bundler convention and+ it is what makes the flagship edge work — ``ui/index.html`` writing+ ``/src/main.tsx`` means ``ui/src/main.tsx``. Only accepted when that file+ actually exists, so it cannot invent anything.+ b. Its ``public/`` subdirectory, which Vite, CRA and Vue CLI copy to the+ web root verbatim — ``ui/index.html`` writing ``/ico/favicon.png`` means+ ``ui/public/ico/favicon.png``.+ c. Failing both, a unique path suffix anywhere in the repo, for the+ server-rooted case (``templates/page.html`` referencing+ ``/static/app.css`` that lives in ``myapp/static/app.css``). Only when+ exactly one repo path ends with it — a tie yields no edge rather than a+ guessed one.++ The order matters in a monorepo: nine files end in ``/src/main.tsx`` in the+ validation corpus, so suffix matching alone correctly refuses to guess and+ the real edge is lost. Anchoring at the page's directory finds it.++External references (CDN URLs, ``data:``) never arrive: the extractor drops+them, since they name no file in the repository.+"""++from __future__ import annotations++import posixpath+from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from .context import ResolverContext+++def resolve_html_asset(+ module_path: str,+ importer_path: str,+ ctx: ResolverContext,+) -> str | None:+ """Resolve one HTML asset reference to a repo-relative path, or None."""+ raw = module_path.strip()+ if not raw:+ return None++ # A query string or fragment is cache-busting or a sprite selector+ # ("app.js?v=3", "icons.svg#home") — not part of the filename.+ for sep in ("?", "#"):+ raw = raw.split(sep, 1)[0]+ raw = raw.strip()+ if not raw or raw.endswith("/"):+ return None++ importer_dir = posixpath.dirname(importer_path)++ if raw.startswith("/"):+ tail = raw.lstrip("/")+ # (a) the page's own directory as the web root — the bundler convention.+ anchored = posixpath.normpath(posixpath.join(importer_dir, tail))+ if anchored in ctx.path_set:+ return anchored+ # (b) its public/ directory, which Vite, CRA and Vue CLI all copy to+ # the web root verbatim.+ public = posixpath.normpath(posixpath.join(importer_dir, "public", tail))+ if public in ctx.path_set:+ return public+ # (c) otherwise a unique suffix anywhere in the repo.+ return _unique_suffix_match(tail, ctx)++ resolved = posixpath.normpath(posixpath.join(importer_dir, raw))+ # A page at the repo root referencing "../vendor/x.js" escapes the repo.+ if resolved.startswith("..") or resolved in (".", "/"):+ return None+ if resolved in ctx.path_set:+ return resolved++ # A page is often served from a directory that is not where it lives in the+ # repo (templates/index.html serving /static/app.js as "static/app.js"), so+ # a bare relative miss gets the same unique-suffix treatment. Multi-segment+ # only: linking a lone "app.js" by filename would be a guess.+ if "/" in raw:+ return _unique_suffix_match(raw, ctx)+ return None+++def _unique_suffix_match(tail: str, ctx: ResolverContext) -> str | None:+ """Return the single repo path ending in *tail*, else None.++ Same precision guard as the shell resolver: exactly one match links, a tie+ links nothing. A wrong asset edge is worse than a missing one for a graph+ that feeds docs and dead-code detection.+ """+ tail = posixpath.normpath(tail)+ if tail in ctx.path_set:+ return tail+ needle = f"/{tail}"+ hits = [p for p in ctx.sorted_paths if p.endswith(needle)]+ return hits[0] if len(hits) == 1 else Nonediff --git a/tests/unit/ingestion/test_html_imports.py b/tests/unit/ingestion/test_html_imports.pynew file mode 100644index 000000000..bab3fad3b--- /dev/null+++ b/tests/unit/ingestion/test_html_imports.py@@ -0,0 +1,256 @@+"""HTML import extraction and asset resolution.++The tier is deliberately narrow — ``<script src>`` and ``<link href>``, no+symbols — so these tests pin both what it captures and what it refuses to.+"""++from __future__ import annotations++from datetime import datetime+from pathlib import Path++import networkx as nx+import pytest++from repowise.core.ingestion.languages.registry import REGISTRY+from repowise.core.ingestion.lightweight_imports import extract_lightweight_imports+from repowise.core.ingestion.lightweight_imports.html import extract_html_imports+from repowise.core.ingestion.models import EXTENSION_TO_LANGUAGE, FileInfo+from repowise.core.ingestion.resolvers import resolve_import+from repowise.core.ingestion.resolvers.context import ResolverContext+++def _modules(source: str) -> list[str]:+ return [i.module_path for i in extract_html_imports(source)]+++def _ctx(paths: set[str]) -> ResolverContext:+ return ResolverContext(path_set=paths, stem_map={}, graph=nx.DiGraph())+++def _resolve(module: str, importer: str, paths: set[str]) -> str | None:+ return resolve_import(module, importer, "html", _ctx(paths))+++class TestExtraction:+ def test_script_src_and_link_href(self) -> None:+ assert _modules(+ '<link rel="stylesheet" href="site.css">\n<script src="app.js"></script>'+ ) == ["site.css", "app.js"]++ def test_unquoted_attribute_value(self) -> None:+ """A regex keyed on quotes would miss this; the grammar does not."""+ assert _modules("<script src=app.js></script>") == ["app.js"]++ def test_attribute_split_across_lines(self) -> None:+ assert _modules('<script\n type="module"\n src="m.js"></script>') == ["m.js"]++ def test_single_quoted_value(self) -> None:+ assert _modules("<script src='app.js'></script>") == ["app.js"]++ def test_commented_out_reference_is_not_an_import(self) -> None:+ assert _modules('<!-- <script src="old.js"></script> -->') == []++ def test_inline_script_without_src_yields_nothing(self) -> None:+ assert _modules('<script>import x from "./m.js";</script>') == []++ def test_anchor_and_image_are_not_dependencies(self) -> None:+ assert _modules('<a href="p.html">x</a><img src="logo.png">') == []++ def test_duplicate_reference_recorded_once(self) -> None:+ assert _modules('<script src="a.js"></script><script src="a.js"></script>') == ["a.js"]++ def test_empty_value_is_skipped(self) -> None:+ assert _modules('<script src=""></script>') == []++ @pytest.mark.parametrize(+ "ref",+ [+ "//cdn.example.com/x.js",+ "https://example.com/x.js",+ "http://example.com/x.js",+ "data:text/javascript,void%200",+ "#anchor",+ "mailto:[email protected]",+ "javascript:void(0)",+ ],+ )+ def test_external_reference_is_dropped(self, ref: str) -> None:+ assert _modules(f'<script src="{ref}"></script>') == []++ @pytest.mark.parametrize(+ "ref",+ [+ "{{ url_for('static', filename='x.js') }}",+ "{% static 'x.js' %}",+ "<%= asset_path('x.js') %>",+ "${baseUrl}/x.js",+ ],+ )+ def test_template_expression_is_not_a_static_path(self, ref: str) -> None:+ assert _modules(f'<script src="{ref}"></script>') == []++ def test_is_relative_distinguishes_root_from_document(self) -> None:+ imports = extract_html_imports(+ '<script src="/static/a.js"></script><script src="./b.js"></script>'+ )+ assert [(i.module_path, i.is_relative) for i in imports] == [+ ("/static/a.js", False),+ ("./b.js", True),+ ]++ def test_non_ascii_markup_is_safe(self) -> None:+ assert _modules('<p>héllo — ünicode</p><script src="app.js"></script>') == ["app.js"]++ def test_template_dialect_file_degrades_to_nothing(self) -> None:+ """The declared ceiling, pinned so it cannot regress silently."""+ assert _modules('{% extends "base.html" %}\n{% include "nav.html" %}') == []+++class TestResolution:+ def test_document_relative(self) -> None:+ assert _resolve("./app.js", "web/index.html", {"web/app.js"}) == "web/app.js"++ def test_bare_relative(self) -> None:+ assert _resolve("app.js", "web/index.html", {"web/app.js"}) == "web/app.js"++ def test_parent_relative(self) -> None:+ assert _resolve("../shared/x.js", "web/p/i.html", {"web/shared/x.js"}) == "web/shared/x.js"++ def test_root_relative_matches_by_unique_suffix(self) -> None:+ """``/static/js/app.js`` is a *web* root, which is not the repo root."""+ assert (+ _resolve("/static/js/app.js", "templates/i.html", {"myapp/static/js/app.js"})+ == "myapp/static/js/app.js"+ )++ def test_root_relative_anchors_at_the_page_directory_first(self) -> None:+ """The Vite/webpack convention: index.html's own dir is the web root."""+ paths = {"web/ui/index.html", "web/ui/src/main.tsx"}+ assert _resolve("/src/main.tsx", "web/ui/index.html", paths) == "web/ui/src/main.tsx"++ def test_page_directory_anchor_wins_over_an_ambiguous_suffix(self) -> None:+ """Nine files end in /src/main.tsx in the validation corpus, so suffix+ matching alone refuses to guess and the real SPA entry edge is lost."""+ paths = {+ "apps/a/index.html",+ "apps/a/src/main.tsx",+ "apps/b/src/main.tsx",+ "apps/c/src/main.tsx",+ }+ assert _resolve("/src/main.tsx", "apps/a/index.html", paths) == "apps/a/src/main.tsx"++ def test_root_relative_falls_through_to_public_dir(self) -> None:+ """Vite/CRA/Vue CLI copy public/ to the web root verbatim."""+ paths = {"ui/index.html", "ui/public/ico/favicon.png"}+ assert _resolve("/ico/favicon.png", "ui/index.html", paths) == "ui/public/ico/favicon.png"++ def test_page_directory_anchor_beats_public_dir(self) -> None:+ paths = {"ui/index.html", "ui/src/main.tsx", "ui/public/src/main.tsx"}+ assert _resolve("/src/main.tsx", "ui/index.html", paths) == "ui/src/main.tsx"++ def test_page_directory_anchor_never_invents_a_file(self) -> None:+ """Anchoring only accepts a path that actually exists."""+ paths = {"web/ui/index.html", "elsewhere/src/main.tsx"}+ assert _resolve("/src/main.tsx", "web/ui/index.html", paths) == "elsewhere/src/main.tsx"++ def test_root_relative_at_repo_root(self) -> None:+ assert _resolve("/app.js", "index.html", {"app.js"}) == "app.js"++ def test_ambiguous_suffix_yields_no_edge(self) -> None:+ paths = {"a/static/app.js", "b/static/app.js"}+ assert _resolve("/static/app.js", "i.html", paths) is None++ def test_query_string_is_stripped(self) -> None:+ assert _resolve("app.js?v=3", "index.html", {"app.js"}) == "app.js"++ def test_fragment_is_stripped(self) -> None:+ assert _resolve("icons.svg#home", "index.html", {"icons.svg"}) == "icons.svg"++ def test_missing_target_yields_no_edge(self) -> None:+ assert _resolve("./nope.js", "index.html", {"app.js"}) is None++ def test_no_extension_inference(self) -> None:+ """HTML fetches paths literally — ``src="./app"`` is not ``app.js``."""+ assert _resolve("./app", "index.html", {"app.js"}) is None++ def test_no_index_lookup(self) -> None:+ assert _resolve("./lib", "index.html", {"lib/index.js"}) is None++ def test_escaping_the_repo_yields_no_edge(self) -> None:+ assert _resolve("../../etc/passwd", "index.html", {"app.js"}) is None++ def test_directory_reference_yields_no_edge(self) -> None:+ assert _resolve("/static/", "index.html", {"static/app.js"}) is None++ def test_single_segment_relative_miss_is_not_guessed(self) -> None:+ """A bare filename that misses locally is too ambiguous to link."""+ assert _resolve("app.js", "web/i.html", {"other/place/app.js"}) is None+++class TestRegistryWiring:+ def test_extensions_map_to_html(self) -> None:+ assert EXTENSION_TO_LANGUAGE[".html"] == "html"+ assert EXTENSION_TO_LANGUAGE[".htm"] == "html"++ def test_tier_is_partial_not_full(self) -> None:+ assert REGISTRY.import_support_for("html") == "partial"++ def test_markup_not_code(self) -> None:+ spec = REGISTRY.get("html")+ assert spec is not None+ assert spec.is_code is False+ assert spec.is_passthrough is True++ def test_never_reported_as_dead_code(self) -> None:+ """Reachability of a page is not statically decidable, and committed+ generated HTML is everywhere — so the language is exempt outright."""+ from repowise.core.analysis.dead_code.constants import _NON_CODE_LANGUAGES++ assert "html" in _NON_CODE_LANGUAGES++ def test_index_html_is_an_entry_point(self) -> None:+ assert "index.html" in REGISTRY.entry_point_names()++ def test_no_sfc_locator_registered(self) -> None:+ """HTML earns no projection: it has no component and no symbols."""+ from repowise.core.ingestion.sfc_source import _LOCATORS, prepare_source++ assert "html" not in _LOCATORS+ source = b'<script src="a.js"></script>'+ assert prepare_source("html", source) == source++ def test_reaches_the_parser_via_the_lightweight_path(self) -> None:+ info = FileInfo(+ path="web/index.html",+ abs_path="/repo/web/index.html",+ language="html",+ size_bytes=0,+ git_hash="",+ last_modified=datetime.now(),+ is_test=False,+ is_config=False,+ is_api_contract=False,+ is_entry_point=True,+ )+ imports = extract_lightweight_imports(info, b'<script src="app.js"></script>')+ assert [i.module_path for i in imports] == ["app.js"]++ def test_parse_file_yields_imports_and_no_symbols(self, tmp_path: Path) -> None:+ from repowise.core.ingestion.parser import ASTParser++ info = FileInfo(+ path="index.html",+ abs_path=str(tmp_path / "index.html"),+ language="html",+ size_bytes=0,+ git_hash="",+ last_modified=datetime.now(),+ is_test=False,+ is_config=False,+ is_api_contract=False,+ is_entry_point=True,+ )+ parsed = ASTParser().parse_file(info, b'<script type="module" src="/src/main.ts"></script>')+ assert parsed.symbols == []+ assert [i.module_path for i in parsed.imports] == ["/src/main.ts"]diff --git a/tests/unit/ingestion/test_language_capabilities.py b/tests/unit/ingestion/test_language_capabilities.pyindex 44aed6767..a48cada54 100644--- a/tests/unit/ingestion/test_language_capabilities.py+++ b/tests/unit/ingestion/test_language_capabilities.py@@ -166,6 +166,10 @@ _PARTIAL = {"sql",# source ./lib.sh + $SCRIPT_DIR / dirname idioms."shell",+ # <script src>/<link href> as document-/root-relative asset paths. Partial+ # rather than full because template dialects (Django, Jinja, Go templates,+ # ERB, Handlebars) are invisible to an HTML grammar and yield nothing.+ "html",}diff --git a/tests/unit/ingestion/test_lightweight_resolvers.py b/tests/unit/ingestion/test_lightweight_resolvers.pyindex a8bdee97b..922c00763 100644--- a/tests/unit/ingestion/test_lightweight_resolvers.py+++ b/tests/unit/ingestion/test_lightweight_resolvers.py@@ -91,6 +91,8 @@ class TestDispatch:"erlang","fsharp","sql",+ # <script src>/<link href>; AST-backed, unlike its siblings here.+ "html",} == LIGHTWEIGHT_IMPORT_LANGUAGESdef test_other_language_returns_empty(self) -> None: