web: HTML and CSS engine (0.2.0)

.github/e2e/web/css/app.css

@@ -0,0 +1,5 @@
+@import "base.css";
+.nav a { color: navy; }
+.btn { padding: 4px; }
+.btn.primary { color: white; }
+.ghost { opacity: 0.5; }

.github/e2e/web/css/base.css

@@ -0,0 +1,2 @@
+body { margin: 0; }
+.lead { font-size: 1.2em; }

.github/e2e/web/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <link rel="stylesheet" href="css/app.css">
+</head>
+<body>
+  <nav class="nav"><a href="pages/about.html">About</a></nav>
+  <button class="btn primary" id="buy">Buy</button>
+</body>
+</html>

.github/e2e/web/pages/about.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <link rel="stylesheet" href="../css/app.css">
+</head>
+<body>
+  <p class="lead">About us</p>
+  <a class="btn" href="../index.html">Home</a>
+</body>
+</html>

.github/scripts/e2e-install.sh

@@ -62,6 +62,24 @@ grep -q "using packaged engine" "$W/run.log" || fail "the run did not use the in
 
 db="$(find "$W/out" -name graph.sqlite | head -1)"
 [ -n "$db" ] || fail "no graph.sqlite was written"
+
+# WEB (HTML + CSS) has no call graph: the installed package must have used its packaged web engine (checked above) and
+# written pages, selectors and the rows that link them; then every query verb on .github/e2e/web (e2e-web-queries.sh).
+if [ "$lang" = "web" ]; then
+  counts="$(node -e '
+    const { DatabaseSync } = require("node:sqlite");
+    const db = new DatabaseSync(process.argv[1], { readOnly: true });
+    const n = (t) => db.prepare(`SELECT COUNT(*) AS n FROM ${t}`).get().n;
+    console.log([n("web_pages"), n("web_selectors"), n("web_styles"), n("ext_web_selector_match")].join(" "));
+  ' "$db" 2>/dev/null)"
+  read -r pages sels styles matches <<<"${counts:-0 0 0 0}"
+  [ "${pages:-0}" -gt 0 ] && [ "${sels:-0}" -gt 0 ] && [ "${styles:-0}" -gt 0 ] && [ "${matches:-0}" -gt 0 ] \
+    || fail "the web graph is missing rows (pages ${pages:-?}, selectors ${sels:-?}, styles ${styles:-?}, engine matches ${matches:-?})"
+  echo "── every query verb on the web fixture, answers checked, no souffle"
+  PATH="$SANDBOX_PATH" bash "$root/.github/scripts/e2e-web-queries.sh" "$bin" "$root/.github/e2e/web" "$W/q" || fail "a web query verb answered wrongly (above)"
+  echo "e2e: ok — installed from the tarballs, used the packaged $platform web engine; $pages page(s), $sels selector(s), $styles style row(s), $matches engine match(es); every query verb answered correctly from the package"
+  exit 0
+fi
 edges="$(node -e '
   const { DatabaseSync } = require("node:sqlite");
   const db = new DatabaseSync(process.argv[1], { readOnly: true });

.github/scripts/e2e-web-queries.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# Every query verb returns the RIGHT answer on a tiny site whose answers are known — the web (HTML + CSS) twin of
+# e2e-queries.sh, which needs a call graph (entry → helper → leaf) a site does not have.
+#
+#   e2e-web-queries.sh <axiomcode-bin> <fixture-dir> <work-dir>
+#
+# <fixture-dir> is .github/e2e/web/: index.html and pages/about.html load css/app.css, which @imports css/base.css;
+# .btn is carried by an element on each page, .ghost by none. The site is copied to <work-dir>, committed, indexed,
+# and asked:
+#
+#   impact .btn               the elements carrying it (one per page) and the selectors naming it
+#   impact css/app.css        both pages load it; it imports base.css; .ghost matches nothing
+#   impact index.html         about.html links to it; it loads base.css (import) and app.css (link), in that order
+#   path index.html css/base.css   index.html → css/app.css → css/base.css
+#   context .ghost            lands on css/app.css:5
+#   impact .btn --json        one JSON document naming the class
+#   impact, path, context with os.exec* ending the caller at once, as Windows' exec does (#1640)
+#   padding 4px becomes 6px, then
+#   impact (no name)          names the edited rule and the elements it styles
+#   tests                     says the web graph selects none (HTML and CSS have none), exit 3
+#
+# A path is matched with either separator; no answer may carry a Python traceback.
+# ─────────────────────────────────────────────────────────────────────────────
+set -uo pipefail
+bin="${1:?usage: e2e-web-queries.sh <axiomcode-bin> <fixture-dir> <work-dir>}"; fx="${2:?fixture-dir}"; R="${3:?work-dir}"
+fail() { echo "::error::e2e web queries: $*"; exit 1; }
+native_path() { case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) cygpath -w "$1";; *) printf '%s' "$1";; esac; }
+rm -rf "$R"; mkdir -p "$R"; cp -R "$fx"/. "$R"/
+git -C "$R" init -q && git -C "$R" add -A && git -C "$R" -c user.email=e2e@axiomcode -c user.name=e2e commit -qm base \
+  || fail "could not commit the fixture"
+
+"$bin" index "$R" > "$R/.index.log" 2>&1 || { tail -20 "$R/.index.log"; fail "axiomcode index exited non-zero"; }
+
+run() {  # <env> <verb and args…>: the answer lands in $R/.q.log, a non-zero exit or a traceback fails
+  local env="$1"; shift; LABEL="$* ${env:+($env)}"
+  ( cd "$R" && env $env "$bin" "$@" ) > "$R/.q.log" 2>&1; local rc=$?
+  if [ "$rc" -ne 0 ] || grep -q 'Traceback (most recent call last)' "$R/.q.log"; then
+    sed 's/^/     /' "$R/.q.log" | head -25; fail "$LABEL: rc=$rc"
+  fi
+}
+must() {  # <extended regex> the last answer has to match, and why
+  grep -Eq -- "$1" "$R/.q.log" || { sed 's/^/     /' "$R/.q.log" | head -30; fail "$LABEL: expected /$1/ ($2)"; }
+  echo "   ok  $LABEL  — $2"
+}
+S='[/\\]'  # a path separator, either way round
+btn_ok() {  # <why>: the last answer is .btn's impact
+  must "^ +index\.html:8: button#buy\.btn\.primary" "$1 (the button on index.html)"
+  must "^ +pages${S}about\.html:8: a\.btn" "$1 (the link on about.html)"
+  must "css${S}app\.css:3: \.btn " "$1 (the selector naming it)"
+}
+path_ok() {  # <why>: the last answer is the chain index.html → app.css → base.css
+  must "chain \(2 hop\(s\)\)" "$1 (two hops)"
+  must "^ +css${S}app\.css +loads " "$1 (index.html loads app.css)"
+  must "^ +css${S}base\.css +@import " "$1 (app.css imports base.css)"
+}
+ghost_ok() { must "css${S}app\.css:5: selector \.ghost" "$1 (.ghost is css/app.css:5)"; }
+
+run "" impact .btn;                             btn_ok "the elements and selectors of .btn"
+run "" impact css/app.css;                      must "^pages that load it: 2" "both pages load app.css"
+                                                must "^ +css${S}base\.css \[match\]" "app.css imports base.css"
+                                                must "css${S}app\.css:5: \.ghost +\[no_static_carrier\]" ".ghost matches nothing"
+run "" impact index.html;                       must "^ +pages${S}about\.html:8: a\.btn \[href\]" "about.html links to it"
+                                                must "^ +1\. css${S}base\.css +\[import" "base.css first in cascade order"
+                                                must "^ +2\. css${S}app\.css +\[link\]" "app.css second"
+run "" path index.html css/base.css;            path_ok "the page reaches the imported sheet"
+run "" context .ghost;                          ghost_ok "context lands on the selector"
+run "" impact .btn --json;                      must '"target": "\.btn"' "the JSON names .btn"
+node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$(native_path "$R/.q.log")" \
+  || { head -c 600 "$R/.q.log"; fail "impact --json is not one JSON document"; }
+
+# ── os.exec* that does not replace the process, as on Windows (#1640) ─────────────────────────
+NOEXEC="$R.noexec"; mkdir -p "$NOEXEC"
+cat > "$NOEXEC/sitecustomize.py" <<'PY'
+import os, subprocess, sys
+def _leave(path, args, *env):
+    subprocess.Popen(list(args), executable=path if os.sep in path else None, stdin=subprocess.DEVNULL,
+                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    os._exit(0)
+for _n in ('execv', 'execve', 'execvp', 'execvpe'): setattr(os, _n, _leave)
+for _n in ('execl', 'execle', 'execlp', 'execlpe'): setattr(os, _n, lambda path, *args: _leave(path, args))
+sys.path.insert(0, os.environ.get('E2E_AX_SCRIPTS', ''))
+try:
+    import ax_exec; ax_exec.REPLACES = False
+except ImportError: pass
+finally: sys.path.pop(0)
+PY
+SCR="$(cd "$(dirname "$bin")/../@axiomcode/code-graph/plugins/axiomcode/skills/axiomcode/scripts" 2>/dev/null && pwd)"
+[ -n "$SCR" ] || fail "the installed package has no plugin scripts next to $bin"
+NX="PYTHONPATH=$(native_path "$NOEXEC") E2E_AX_SCRIPTS=$(native_path "$SCR")"
+run "$NX" impact .btn;                          btn_ok "impact answers where exec does not replace the process"
+run "$NX" path index.html css/base.css;         path_ok "path answers where exec does not replace the process"
+run "$NX" context .ghost;                       ghost_ok "context answers where exec does not replace the process"
+
+# a real edit to a rule: what changed, and what it styles
+sed 's/padding: 4px/padding: 6px/' "$R/css/app.css" > "$R/.edit" && mv "$R/.edit" "$R/css/app.css"
+git -C "$R" diff --quiet && fail "the edit to css/app.css changed nothing"
+run "" impact;                                  must "^web: your edits" "the edit is reported"
+                                                must "^ +css${S}app\.css: rule at line 3" "the edited rule is css/app.css:3"
+                                                must "^ +pages${S}about\.html:8: a\.btn \[match\]" "it styles the link on about.html"
+# tests: an empty selection is exit 3 (as every verb's "nothing found"), never 0 and never a crash
+LABEL="tests"; ( cd "$R" && "$bin" tests ) > "$R/.q.log" 2>&1; rc=$?
+[ "$rc" -eq 3 ] && ! grep -q 'Traceback (most recent call last)' "$R/.q.log" \
+  || { sed 's/^/     /' "$R/.q.log" | head -25; fail "tests: rc=$rc (expected 3, an empty selection)"; }
+                                                must "web graph selects no tests" "HTML and CSS have no tests to select"
+echo "e2e web queries: every verb answered correctly"

.github/workflows/build-engines.yml

@@ -44,7 +44,8 @@ on:
 # for exactly the rules it was built from; the smoke step still runs every one.
 
 env:
-  LANGUAGES: java typescript python javascript csharp
+  # web: the HTML + CSS engine (graph/web). It is built, marked .parallel and solved at -j 8 like every other.
+  LANGUAGES: java typescript python javascript csharp web
   # Same pin and checksum as ci.yml: the tool that produces the published binaries is
   # verified against what upstream published for that release.
   SOUFFLE_SHA512: '6b86e554f6aa5abf8a8b55d8312ae37c0957c5bd6c9edeea89246db9406f645ec5e600b84fe6636b1c163da556f0da6c3d2dad46c1083413f2fcf4f95b9ac62c'
@@ -229,7 +230,7 @@ jobs:
         if: startsWith(matrix.target.platform, 'win32')
         shell: cmd
         run: |
-          for %%L in (java typescript python javascript csharp) do (
+          for %%L in (java typescript python javascript csharp web) do (
             fc /b gen\%%L.id engines\%%L\ENGINE_ID >nul 2>&1
             if errorlevel 1 (
               if not exist engines\%%L mkdir engines\%%L
@@ -298,9 +299,11 @@ jobs:
           for lang in $LANGUAGES; do
             # the binary itself, not the .parallel marker (or a DLL) beside it
             bin="engines/$lang/axiomcode-engine-$lang"; [ -f "$bin.exe" ] && bin="$bin.exe"; chmod +x "$bin" 2>/dev/null || true
+            # every shipped engine is the parallel flavor: without the marker run-souffle.sh would solve it at -j 1
+            [ -f "$bin.parallel" ] || { echo "::error::$lang has no .parallel marker beside $bin"; exit 1; }
             mkdir -p "facts-$lang" "out-$lang"
             sed -n 's/^\.input \([A-Za-z0-9_]*\)(.*/\1/p' "gen/$lang.dl" | while read -r r; do : > "facts-$lang/$r.facts"; done
-            "./$bin" -F "facts-$lang" -D "out-$lang"
+            "./$bin" -j 8 -F "facts-$lang" -D "out-$lang"
             echo "$lang: ok ($(ls out-$lang | wc -l) relations written)"
           done
           bash gen/queries/smoke.sh check gen/queries engines/queries
@@ -408,7 +411,8 @@ jobs:
           for lang in $LANGUAGES; do
             mkdir -p "facts-$lang" "out-$lang"
             sed -n 's/^\.input \([A-Za-z0-9_]*\)(.*/\1/p' "gen/$lang.dl" | while read -r r; do : > "facts-$lang/$r.facts"; done
-            "./engines/$lang/axiomcode-engine-$lang" -F "facts-$lang" -D "out-$lang"
+            [ -f "engines/$lang/axiomcode-engine-$lang.parallel" ] || { echo "::error::$lang has no .parallel marker"; exit 1; }
+            "./engines/$lang/axiomcode-engine-$lang" -j 8 -F "facts-$lang" -D "out-$lang"
           done
           bash gen/queries/smoke.sh check gen/queries engines/queries
       - name: save the engines for the next run

.github/workflows/ci.yml

@@ -169,6 +169,7 @@ jobs:
       - name: IR staging maps are consistent
         run: |
           fail=0
+          # web stages no library (graph/web/templates/staging.conf), so it has no maps to compare
           for lang in java typescript python javascript csharp; do
             echo "── $lang"
             python3 graph/test/tools/check_staging.py --lang "$lang" || fail=1
@@ -183,7 +184,7 @@ jobs:
       - name: engine declarations match the parser schema
         run: |
           fail=0
-          for pair in typescript:decls_base_ts.dl python:decls_base_py.dl javascript:decls_base_js.dl csharp:decls_base_cs.dl; do
+          for pair in typescript:decls_base_ts.dl python:decls_base_py.dl javascript:decls_base_js.dl csharp:decls_base_cs.dl web:decls_base_web.dl; do
             lang="${pair%%:*}"; file="${pair#*:}"
             if ! diff <(grep '^\.decl' "parser/src/schema/$lang/$file") \
                       <(grep '^\.decl' "graph/$lang/souffle/decls_base.dl"); then
@@ -309,6 +310,11 @@ jobs:
           # .NET 8 SDK. No flag — scoring against the compiler is all it does.
           - lang: csharp
             oracle: ''
+          # Web (HTML + CSS): every case is gated against the oracle's rows (parse5, postcss, css-select,
+          # graph/test/web/oracle), reviewed by hand; no flag. Its query cases go through the plugin's
+          # front door, which reads AXIOMCODE_ENGINE (set below to this checkout).
+          - lang: web
+            oracle: ''
     steps:
       - uses: actions/checkout@v4
 
@@ -448,8 +454,14 @@ jobs:
           path: .souffle-cache
           key: souffle-engine-${{ matrix.lang }}-${{ steps.eid.outputs.id }}-${{ hashFiles('graph/pipeline/run-souffle.sh') }}-march-${{ env.AXIOM_ENGINE_MARCH }}
 
+      # the web suite records each build's peak memory with /usr/bin/time, which a runner image does not always carry
+      - name: install time (web)
+        if: matrix.lang == 'web'
+        run: sudo apt-get install -y --no-install-recommends time
+
       - name: ${{ matrix.lang }} regression suite
         env:
+          AXIOMCODE_ENGINE: ${{ github.workspace }}
           AXIOM_PARSER: ${{ github.workspace }}/parser/dist/index.js
           # The driver's default cache is ~/.cache/axiomcode/souffle; point it at the
           # directory the cache step above saves and restores, or it never hits.
@@ -458,11 +470,23 @@ jobs:
         # AXIOM_SUITE_JOBS=1 here would run them one at a time, as they used to.
         run: bash .github/scripts/run-suite.sh ${{ matrix.lang }} ${{ matrix.oracle }}
 
+      - name: web CLI, violation and include checks
+        if: matrix.lang == 'web'
+        env:
+          AXIOMCODE_ENGINE: ${{ github.workspace }}
+          AXIOM_PARSER: ${{ github.workspace }}/parser/dist/index.js
+          AXIOM_SOUFFLE_CACHE: ${{ github.workspace }}/.souffle-cache
+        run: |
+          rc=0
+          for s in cli-smoke violations includes; do bash "graph/test/web/$s.sh" || rc=1; done
+          exit $rc
+
       # THE QUERY LAYER'S CASES (tests/run.py): what impact, path, context, changed and test-impact answer on small
       # projects written for one behaviour each. Every case must pass, and a case marked pending that now passes fails
       # the run until the mark is removed, so a fix for one shape cannot quietly break another's answer. The suite
       # calls the verbs directly, so it checks their own answers, not the front-door rendering (tests/front_door.py).
       - name: ${{ matrix.lang }} query cases
+        if: matrix.lang != 'web'
         env:
           AXIOM_PARSER: ${{ github.workspace }}/parser/dist/index.js
           AXIOM_SOUFFLE_CACHE: ${{ github.workspace }}/.souffle-cache
@@ -572,9 +596,14 @@ jobs:
           set -euo pipefail
           command -v souffle && { echo "::error::this runner has souffle; the gate would not prove anything"; exit 1; }
           export CODEGRAPH_TGZ="$(ls "$PWD"/artifacts/tgz/*.tgz)"
-          for lang in java typescript python javascript csharp; do
+          for lang in java typescript python javascript csharp web; do
             # A glob, not ls | head: under pipefail, head exiting early SIGPIPEs ls and fails the step.
-            cases=(graph/test/"$lang"/cases/*/src)
+            # a web case is one packed file (cases/<suite>/<case>.case) unpacked first; this one has selectors the engine matches
+            if [ "$lang" = web ]; then
+              packed=(graph/test/web/cases/cascade/01-*.case)
+              python3 graph/test/web/tools/cases.py unpack "${packed[0]}" "$RUNNER_TEMP/web-case"
+              cases=("$RUNNER_TEMP/web-case/src")
+            else cases=(graph/test/"$lang"/cases/*/src); fi
             case_dir="${cases[0]}"
             [ -d "$case_dir" ] || { echo "::error::no $lang case under graph/test/$lang/cases"; exit 1; }
             echo "::group::$lang ($case_dir)"

.github/workflows/nightly.yml

@@ -75,10 +75,15 @@ jobs:
       - name: every language, installed from the tarballs, no Soufflé
         run: |
           set -euo pipefail
-          for pair in java:java typescript:typescript python:python javascript:javascript; do
+          for pair in java:java typescript:typescript python:python javascript:javascript web:web; do
             lang="${pair%%:*}"
             # A glob, not ls | head: under pipefail, head exiting early SIGPIPEs ls and fails the step.
-            cases=(graph/test/"$lang"/cases/*/src)
+            # a web case is one packed file (cases/<suite>/<case>.case) unpacked first; this one has selectors the engine matches
+            if [ "$lang" = web ]; then
+              packed=(graph/test/web/cases/cascade/01-*.case)
+              python3 graph/test/web/tools/cases.py unpack "${packed[0]}" "$RUNNER_TEMP/web-case"
+              cases=("$RUNNER_TEMP/web-case/src")
+            else cases=(graph/test/"$lang"/cases/*/src); fi
             case_dir="${cases[0]}"
             [ -d "$case_dir" ] || { echo "::error::no $lang case under graph/test/$lang/cases"; exit 1; }
             bash .github/scripts/e2e-install.sh artifacts/engines-linux-x64 linux-x64 "$lang" "$case_dir"