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): HTML at the import tier via script src and link href (#1235)

Raghav Chamadiya3ee0f0741844
diff --git a/README.md b/README.md
index 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 changes
to the parser core. Full matrix and the contributor recipe:
diff --git a/docs/architecture/language-support.md b/docs/architecture/language-support.md
index 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 SFC
cleanly 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 are
quotes rather than braces, and why only directive attributes (`:`, `@`, `v-`)
diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.md
index 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, and
code-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 are
worth calling out. For **.NET**, as one example:
diff --git a/docs/layers/LANGUAGE_SUPPORT.md b/docs/layers/LANGUAGE_SUPPORT.md
index 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 imports
fully.
² 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__.py
index 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 _FSHARP
from .go import SPEC as _GO
from .graphql import SPEC as _GRAPHQL
from .haskell import SPEC as _HASKELL
+from .html import SPEC as _HTML
from .java import SPEC as _JAVA
from .javascript import SPEC as _JAVASCRIPT
from .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 so
diff --git a/packages/core/src/repowise/core/ingestion/languages/specs/html.py b/packages/core/src/repowise/core/ingestion/languages/specs/html.py
new file mode 100644
index 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__.py
index 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_imports
from .erlang import extract_erlang_imports
from .fsharp import extract_fsharp_imports
from .haskell import extract_haskell_imports
+from .html import extract_html_imports
from .lean import extract_lean_imports
from .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.py
new file mode 100644
index 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 imports
diff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.py
index 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__.py
index 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_import
from .generic import resolve_generic_import
from .go import resolve_go_import
from .haskell import resolve_haskell_import
+from .html import resolve_html_asset
from .java import resolve_java_import
from .kotlin import resolve_kotlin_import
from .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.py
new file mode 100644
index 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 None
diff --git a/tests/unit/ingestion/test_html_imports.py b/tests/unit/ingestion/test_html_imports.py
new file mode 100644
index 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.py
index 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.py
index 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_LANGUAGES
def test_other_language_returns_empty(self) -> None: