@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/hooks/scripts/quality-gates.json

@@ -0,0 +1,261 @@
+{
+  "$comment": [
+    "Quality gates run by the Stop hook (cratis-quality-gate.sh).",
+    "Data, not code: a consuming repository overrides this file (or points CRATIS_HOOKS_GATES at",
+    "its own) without touching the script. Gates run in order and stop at the first failure.",
+    "",
+    "A gate runs only when the working tree contains a change matching one of its \"changed\" globs,",
+    "AND every entry in \"requires\" is satisfied, AND its project was discovered. Any of those",
+    "unsatisfied makes the gate a NO-OP with a message on stderr \u2014 that is how a repo that has no",
+    ".NET, no frontend, or no source at all stays quiet.",
+    "",
+    "Gate fields:",
+    "  id               stable identifier, shown in failure output",
+    "  description      one line, shown in the dry-run plan",
+    "  changed          globs (repo-relative) that must match a changed file for the gate to run",
+    "  excludeChanged   globs that never count as a relevant change",
+    "  requires.commands executables that must be on PATH",
+    "  requires.paths   repo-relative literal paths that must all exist (no globbing)",
+    "  workingDirectory repo-relative directory the command runs in",
+    "  workingDirectoryFrom  globs identifying the project file this gate builds; the command runs",
+    "                   in that file's directory, and a repository holding none makes the gate a",
+    "                   NO-OP. Globs are tried in order, so the list states a preference. Ignored",
+    "                   when workingDirectory is set.",
+    "  command          argv array \u2014 executed directly, never through a shell (no eval)",
+    "",
+    "No gate names a product's solution, package or source root \u2014 a default that does would",
+    "silently no-op in every repository except the one it was written for. The .NET and frontend",
+    "gates discover the repository's own solution/package instead, so they activate unchanged in",
+    "an application repository, a framework repository, and (as nothing to run) in a corpus-only",
+    "repository such as this one, which carries no .NET or Node project at all.",
+    "",
+    "The override model, in order of increasing force: a repository sets workingDirectory to pin",
+    "one of several candidate projects; or it drops its own quality-gates.json in place of this",
+    "file; or it points CRATIS_HOOKS_GATES at a file anywhere. None of them requires a script fork.",
+    "",
+    "Commands are pinned to .cratis/ai/rules/general.md 'Quality Gates' and .cratis/ai/hooks/agent-stop.md.",
+    "Note the Release build passes -p:CratisProxiesOutputPath= per general.md so the proxy",
+    "generator does not re-run and touch already-correct generated files. That property is the",
+    "only gate: the generator's target is Condition=\"'$(CratisProxiesOutputPath)' != ''\", and",
+    "there is no DisableProxyGenerator property \u2014 MSBuild accepts unknown -p: names silently,",
+    "so passing one looks effective and does nothing. The Debug gate deliberately omits the",
+    "override because general.md makes Debug the canonical proxy-regeneration trigger. A",
+    "consuming repository's own CI should split Debug and Release the same way."
+  ],
+  "enabled": true,
+  "failFast": true,
+  "maxOutputLines": 60,
+  "gates": [
+    {
+      "id": "backend-build-debug",
+      "description": "dotnet build (Debug) \u2014 compiles #if DEBUG spec code and regenerates the TypeScript proxies",
+      "changed": [
+        "**/*.cs",
+        "**/*.csproj",
+        "**/*.slnx",
+        "**/*.sln",
+        "**/*.props",
+        "**/*.targets"
+      ],
+      "excludeChanged": [
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "dotnet"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "*.slnx",
+        "*.sln",
+        "**/*.slnx",
+        "**/*.sln"
+      ],
+      "command": [
+        "dotnet",
+        "build",
+        "--configuration",
+        "Debug"
+      ]
+    },
+    {
+      "id": "backend-specs",
+      "description": "dotnet test (Debug, --no-build) \u2014 zero failures",
+      "changed": [
+        "**/*.cs",
+        "**/*.csproj",
+        "**/*.slnx",
+        "**/*.sln"
+      ],
+      "excludeChanged": [
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "dotnet"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "*.slnx",
+        "*.sln",
+        "**/*.slnx",
+        "**/*.sln"
+      ],
+      "command": [
+        "dotnet",
+        "test",
+        "--configuration",
+        "Debug",
+        "--no-build"
+      ]
+    },
+    {
+      "id": "backend-build-release",
+      "description": "dotnet build (Release) \u2014 build-only check, proxy generation skipped (general.md)",
+      "changed": [
+        "**/*.cs",
+        "**/*.csproj",
+        "**/*.slnx",
+        "**/*.sln",
+        "**/*.props",
+        "**/*.targets"
+      ],
+      "excludeChanged": [
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "dotnet"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "*.slnx",
+        "*.sln",
+        "**/*.slnx",
+        "**/*.sln"
+      ],
+      "command": [
+        "dotnet",
+        "build",
+        "--configuration",
+        "Release",
+        "-p:CratisProxiesOutputPath="
+      ]
+    },
+    {
+      "id": "frontend-lint",
+      "description": "yarn lint:ci \u2014 zero errors",
+      "changed": [
+        "**/*.ts",
+        "**/*.tsx"
+      ],
+      "excludeChanged": [
+        "**/node_modules/**",
+        "**/wwwroot/**",
+        "**/dist/**",
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "yarn"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "package.json",
+        "**/package.json"
+      ],
+      "command": [
+        "yarn",
+        "lint:ci"
+      ]
+    },
+    {
+      "id": "frontend-compile",
+      "description": "yarn g:compile \u2014 zero TypeScript errors",
+      "changed": [
+        "**/*.ts",
+        "**/*.tsx"
+      ],
+      "excludeChanged": [
+        "**/node_modules/**",
+        "**/wwwroot/**",
+        "**/dist/**",
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "yarn"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "package.json",
+        "**/package.json"
+      ],
+      "command": [
+        "yarn",
+        "g:compile"
+      ]
+    },
+    {
+      "id": "frontend-compile-specs",
+      "description": "yarn g:compile:specs \u2014 zero TypeScript errors in specs",
+      "changed": [
+        "**/*.ts",
+        "**/*.tsx"
+      ],
+      "excludeChanged": [
+        "**/node_modules/**",
+        "**/wwwroot/**",
+        "**/dist/**",
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "yarn"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "package.json",
+        "**/package.json"
+      ],
+      "command": [
+        "yarn",
+        "g:compile:specs"
+      ]
+    },
+    {
+      "id": "frontend-specs",
+      "description": "yarn test \u2014 zero failures",
+      "changed": [
+        "**/*.ts",
+        "**/*.tsx"
+      ],
+      "excludeChanged": [
+        "**/node_modules/**",
+        "**/wwwroot/**",
+        "**/dist/**",
+        "**/obj/**",
+        "**/bin/**"
+      ],
+      "requires": {
+        "commands": [
+          "yarn"
+        ]
+      },
+      "workingDirectoryFrom": [
+        "package.json",
+        "**/package.json"
+      ],
+      "command": [
+        "yarn",
+        "test"
+      ]
+    }
+  ]
+}

package/package/corpus/hooks/scripts/type-references-allowlist.txt

@@ -0,0 +1,71 @@
+# Names validate-type-references.sh must never warn about.
+#
+# The Tier 3 index is built from the XML documentation of the Cratis NuGet packages the consuming
+# repository pins, and from what the corpus and that repository's own `Source/**/*.cs` declare for
+# themselves. (`Cratis/AI` itself is a corpus with no C# source, so only the corpus half
+# contributes here and the package half is skipped in silence.) Everything below is a
+# name that is genuinely real and genuinely outside that index — a .NET attribute from an ecosystem
+# whose package ships no XML docs, a Chronicle *Kernel* internal that is in no client package, or a
+# TypeScript API in a repository whose index only covers .NET assemblies.
+#
+# One name per line, `#` starts a comment, blank lines ignored. Every entry states *why* it is here:
+# an entry nobody can justify is an entry that should have been a fix instead. An entry is wrong the
+# moment its name becomes resolvable — the guard silently stops checking it — so prefer widening the
+# index over adding a line here whenever that is possible.
+#
+# Add the bare name, not the `Attribute` suffix; the guard resolves both spellings.
+
+# --- ASP.NET Core, from the Microsoft.AspNetCore.App shared framework ------------------------------
+# The shared framework is a ref pack, and ref packs carry no XML documentation, so no amount of
+# indexing NuGet reaches these. The corpus names them to say what NOT to write (`[Route]` on a
+# model-bound query) or in non-Cratis illustrations.
+FromServices
+HttpGet
+HttpPost
+FromBody
+
+# --- System.ComponentModel.DataAnnotations, from the base class library ---------------------------
+# Same reason: BCL, ref pack, no XML docs. Cited when contrasting DataAnnotations validation with
+# Arc's `CommandValidator<T>` / `ConceptValidator<T>`.
+Required
+Range
+MaxLength
+
+# --- Microsoft.Extensions.* -----------------------------------------------------------------------
+# `[LoggerMessage]` is the logging source generator's attribute; `[FromKeyedServices]` is keyed DI.
+# Both are real; the packages that carry them are transitive here, so their XML docs are not indexed.
+LoggerMessage
+FromKeyedServices
+
+# --- Microsoft Orleans ----------------------------------------------------------------------------
+# `orleans.md` is framework-profile guidance for the Chronicle Kernel's grains. The pinned Orleans
+# packages ship no XML documentation, so `[Alias]` and `[StorageProvider]` cannot be resolved.
+Alias
+StorageProvider
+
+# --- Cratis Chronicle Kernel ----------------------------------------------------------------------
+# `WellKnown` is a Kernel static class (`WellKnown.MeterName`), used by the framework-profile
+# add-traces skill. Kernel internals are not published in any client package, so nothing this guard
+# can read knows about them.
+WellKnown
+
+# --- xUnit -----------------------------------------------------------------------------------------
+# `[Fact]` is xUnit's test attribute. The pinned Cratis packages never reference the test framework,
+# so its attributes cannot appear in this guard's index no matter how wide the pin list grows.
+Fact
+
+# --- The `cratis` CLI -----------------------------------------------------------------------------
+# `[CliCommand]` and `[CliExample]` are `Cratis.Cli.Registration` attributes — verified present as
+# `T:Cratis.Cli.Registration.CliCommandAttribute` / `...CliExampleAttribute` in the Cratis/cli build
+# output. The CLI is a dotnet tool from a separate repository, not a package any application pins,
+# so no Directory.Packages.props entry can ever bring it into the index.
+CliCommand
+CliExample
+
+# --- Cratis TypeScript ----------------------------------------------------------------------------
+# `JsonSerializer` is `@cratis/fundamentals`' TypeScript serializer, referenced from the frontend
+# identity guidance. `ObservableQuery` is the TypeScript class the Arc proxy generator emits for
+# `ISubject<T>` query return types. This guard indexes .NET assemblies only; named TypeScript
+# imports are Tier 2's question, and a bare TypeScript class name is nobody's.
+JsonSerializer
+ObservableQuery

package/package/corpus/hooks/scripts/validate-package-imports.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Tier 2 of the package drift guard. Where validate-package-subpaths.sh asks whether a module
+# specifier resolves, this asks whether the *names* imported through it exist: for every
+# `import { A, B } from '@cratis/<pkg>/<subpath>'` the AI corpus writes, it WARNS about each
+# identifier that appears nowhere in the installed package's `.d.ts` tree.
+#
+# It exists because a subpath that resolves says nothing about what is behind it. `Toaster`,
+# `toastCommandResult`, `PasswordField`, `RatingField` and friends are real APIs of
+# @cratis/components 3.0.0 and absent from 2.6.1; Tier 1 caught the three *subpaths* that moved with
+# them, and the names themselves were only ever found by a human reading package internals.
+#
+# WARN, never fail, and silent when it cannot judge — for the identical reasons spelled out at the
+# top of validate-package-subpaths.sh. A miss is exact; the conclusion drawn from it is not.
+#
+# Deliberately permissive, because a false warning is worse than a missed one. A name counts as
+# present when it appears as a *word anywhere* in the package's `.d.ts` closure — not only in an
+# export position — and the closure follows `export ... from '<other-package>'` re-exports one level
+# out. That admits a name that is merely referenced by the types (an imported PrimeReact symbol, a
+# name in a doc comment) and it still flags every one of the twelve 3.0.0 names above.
+#
+# Portable: bash 3.2 + grep + sed + awk, with `jq` as the one accepted dependency (absent -> silent
+# no-op, per the hook design constraints in ../README.md).
+#
+# Usage: validate-package-imports.sh [root ...]      # default roots: .cratis/ai/rules .cratis/ai/skills .cratis/ai/agents .cratis/ai/prompts
+#        CRATIS_HOOKS_IMPORT_REPORT=1 ...            # also print every binding and its resolved status
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$root"
+
+warn() { printf 'ai-corpus warn: %s\n' "$1" >&2; }
+# `if`, not `A && B || C`: the trailing `|| true` was there to keep a disabled report
+# from failing the caller, but it also swallowed a real printf failure, and shellcheck
+# flags the shape (SC2015) for exactly that reason.
+report() {
+    if [[ "${CRATIS_HOOKS_IMPORT_REPORT:-0}" == "1" ]]; then printf 'ai-corpus import: %s\n' "$1" >&2; fi
+}
+
+command -v jq >/dev/null 2>&1 || exit 0
+[[ -d node_modules/@cratis ]] || exit 0
+
+# `.cratis/ai/hooks` is deliberately not a default root: this file and ../README.md name deliberately-bogus
+# identifiers as examples, and a guard that reports its own documentation is a guard people switch off.
+if [[ $# -gt 0 ]]; then roots=("$@"); else roots=(.cratis/ai/rules .cratis/ai/skills .cratis/ai/agents .cratis/ai/prompts); fi
+scan=()
+for d in "${roots[@]}"; do [[ -d "$d" ]] && scan+=("$d"); done
+[[ "${#scan[@]}" -gt 0 ]] || exit 0
+
+# Same clearing rule, and the same generosity, as Tier 1: a line that carries a version alongside the
+# name has declared the skew on purpose (`(**≥ 3.0.0**)`), so it is not drift.
+version_re='[0-9]+\.[0-9x]+|≥|>='
+
+q="'"
+
+# One awk pass over the corpus emits `file <TAB> line <TAB> package <TAB> specifier <TAB> name` for
+# every named binding of an `@cratis/*` import — single-line and brace-on-its-own-line forms alike,
+# `import type`, `A as B` (the *imported* name is what has to exist), and trailing `//` comments.
+# Anything that does not lex as a plain identifier is dropped rather than guessed at. The quote
+# character arrives as `-v q` so the program itself never has to contain one.
+extract="$(cat <<'AWK'
+FNR == 1 { n = 0; buf = "" }
+{
+    # A blank line, or a second `import`, ends an unterminated buffer rather than being glued onto
+    # it. Without that, a stray `import {` in prose swallows the real statement below it and the
+    # names get read off one block while the specifier is read off another — which invents an
+    # identifier that resolves nowhere, i.e. exactly the false positive this guard must not produce.
+    if (n > 0 && ($0 ~ /^[[:space:]]*$/ || $0 ~ /^[[:space:]]*import[[:space:]]/)) { n = 0; buf = "" }
+    if (n == 0) {
+        if ($0 !~ /^[[:space:]]*import[[:space:]]/) next
+        if (index($0, "{") == 0) next
+        start = FNR; buf = ""
+    }
+    line = $0
+    sub(/\/\/.*$/, "", line)
+    buf = buf " " line
+    n++
+    if (line ~ ("from[[:space:]]*[" q "\"]") || n > 40) { emit(); n = 0; buf = "" }
+}
+function emit(   spec, pkg, names, parts, count, i, name) {
+    if (match(buf, "from[[:space:]]*[" q "\"][^" q "\"]+[" q "\"]") == 0) return
+    spec = substr(buf, RSTART, RLENGTH)
+    sub("^from[[:space:]]*[" q "\"]", "", spec)
+    sub("[" q "\"]$", "", spec)
+    if (spec !~ /^@cratis\//) return
+    pkg = substr(spec, 9)
+    sub(/\/.*$/, "", pkg)
+    if (match(buf, /\{[^}]*\}/) == 0) return
+    names = substr(buf, RSTART + 1, RLENGTH - 2)
+    count = split(names, parts, ",")
+    for (i = 1; i <= count; i++) {
+        name = parts[i]
+        sub(/^[[:space:]]+/, "", name); sub(/[[:space:]]+$/, "", name)
+        sub(/^type[[:space:]]+/, "", name)
+        sub(/[[:space:]]+as[[:space:]].*$/, "", name)
+        sub(/[[:space:]]+$/, "", name)
+        if (name !~ /^[A-Za-z_$][A-Za-z0-9_$]*$/) continue
+        printf "%s\t%d\t%s\t%s\t%s\n", FILENAME, start, pkg, spec, name
+    }
+}
+AWK
+)"
+
+files=()
+while IFS= read -r f; do files+=("$f"); done < <(find "${scan[@]}" -type f 2>/dev/null | LC_ALL=C sort)
+[[ "${#files[@]}" -gt 0 ]] || exit 0
+
+bindings="$(awk -v q="$q" "$extract" "${files[@]}" 2>/dev/null || true)"
+[[ -n "$bindings" ]] || exit 0
+
+# Every `.d.ts` reachable from a package: its own tree, plus one level out through re-exports to
+# another installed package (`export { Messenger } from '@cratis/arc/messaging'`). Intra-package
+# barrels (`export * from './X'`) need no following — the whole tree is read either way.
+closure_dirs() {
+    local pkgdir="node_modules/@cratis/$1" dep
+    printf '%s\n' "$pkgdir"
+    grep -rhE "^[[:space:]]*export[[:space:]][^;]*[[:space:]]from[[:space:]]*[\"$q]" "$pkgdir" --include='*.d.ts' 2>/dev/null \
+        | sed -E "s/.*[\"$q]([^\"$q]*)[\"$q].*/\1/" \
+        | grep -v '^\.' \
+        | sed -E 's#^(@[^/]+/[^/]+|[^@/][^/]*).*#\1#' \
+        | LC_ALL=C sort -u \
+        | while IFS= read -r dep; do
+            [[ -n "$dep" && -d "node_modules/$dep" && "node_modules/$dep" != "$pkgdir" ]] && printf 'node_modules/%s\n' "$dep"
+          done
+}
+
+# Sorted by package so each closure is read exactly once.
+printf '%s\n' "$bindings" | cut -f3,5 | LC_ALL=C sort -u | while IFS="$(printf '\t')" read -r pkg name; do
+    [[ -n "$pkg" && -n "$name" ]] || continue
+
+    if [[ "${current:-}" != "$pkg" ]]; then
+        current="$pkg"; tokens=""; version="?"
+        if [[ -f "node_modules/@cratis/$pkg/package.json" ]]; then
+            version="$(jq -r '.version // "?"' "node_modules/@cratis/$pkg/package.json" 2>/dev/null || printf '?')"
+            dirs=()
+            while IFS= read -r d; do [[ -n "$d" ]] && dirs+=("$d"); done < <(closure_dirs "$pkg")
+            if [[ "${#dirs[@]}" -gt 0 ]]; then
+                tokens="$(grep -rhoE '[A-Za-z_$][A-Za-z0-9_$]*' "${dirs[@]}" --include='*.d.ts' 2>/dev/null | LC_ALL=C sort -u || true)"
+            fi
+        fi
+    fi
+
+    # No package, or a package that ships no type declarations: nothing authoritative to compare
+    # against, so it is not a finding.
+    if [[ -z "$tokens" ]]; then report "$name — skipped (@cratis/$pkg has no installed type declarations)"; continue; fi
+    # A here-string, never `printf … | grep -q`: under `pipefail` an early-exiting `grep -q` closes
+    # the pipe, `printf` dies of SIGPIPE with 141, and the pipeline reports failure even though the
+    # name matched. On a token list this size that is not a rare race — it is every time, and it
+    # manufactures false positives, which is the one thing this guard must not do.
+    if LC_ALL=C grep -qxF -- "$name" <<<"$tokens"; then report "$name — yes (@cratis/$pkg $version)"; continue; fi
+
+    # Qualification is judged per (file, name) exactly as in Tier 1: the corpus states a version
+    # requirement once in prose and then writes the import unqualified in a fenced block below it,
+    # so any line in the file that mentions the name and carries a version clears the file.
+    # One warning per file — the first binding — so a page that repeats an example is not a flood.
+    printf '%s\n' "$bindings" | awk -F'\t' -v p="$pkg" -v n="$name" \
+        '$3 == p && $5 == n { print $1 "\t" $2 "\t" $4 }' \
+        | LC_ALL=C sort -t"$(printf '\t')" -k1,1 -k2,2n -u | awk -F'\t' '!seen[$1]++' \
+        | while IFS="$(printf '\t')" read -r file line spec; do
+            hits="$(grep -nwF -- "$name" "$file" 2>/dev/null || true)"
+            if [[ -n "$hits" ]] && grep -qE "$version_re" <<<"$hits"; then
+                report "$name — missing from @cratis/$pkg $version but version-qualified in $file"
+                continue
+            fi
+            warn "$file:$line: '$name' imported from '$spec' is not declared anywhere in the installed @cratis/$pkg $version — fix the name, or mark the line with the version it needs (e.g. '(≥ 3.0.0)')"
+          done
+done

package/package/corpus/hooks/scripts/validate-package-subpaths.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Resolves every `@cratis/<package>/<subpath>` the AI corpus references against the `exports` map of
+# the package actually installed under node_modules, and WARNS about each one that cannot resolve.
+#
+# WARN, never fail — deliberately. The exports map is exact, but the *conclusion* drawn from a miss
+# is not: "the corpus documents an API that does not exist" and "this repository is pinned behind the
+# version the corpus documents" produce the identical observation. This script is propagated to every
+# Cratis repository and runs in the `ai-corpus` CI job, which checks out the tree and installs
+# nothing — so a fatal verdict would either be a permanent no-op there or turn a repo red for its own
+# dependency pin. A warning is the honest signal: look at this line, decide which of the two it is.
+#
+# Not installed is not a finding. A missing node_modules, a missing @cratis scope, a package this
+# repository does not depend on, and a package published without an `exports` map are all skipped
+# silently — there is nothing authoritative to compare against.
+#
+# Portable: bash 3.2 + grep + sed, with `jq` as the one accepted dependency (absent -> silent no-op,
+# per the hook design constraints in ../README.md).
+#
+# Usage: validate-package-subpaths.sh [root ...]      # default roots: .cratis/ai/rules .cratis/ai/skills .cratis/ai/agents .cratis/ai/prompts
+#        CRATIS_HOOKS_SUBPATH_REPORT=1 ...            # also print every reference and its resolved status
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$root"
+
+warn() { printf 'ai-corpus warn: %s\n' "$1" >&2; }
+# `if`, not `A && B || C`: the trailing `|| true` was there to keep a disabled report
+# from failing the caller, but it also swallowed a real printf failure, and shellcheck
+# flags the shape (SC2015) for exactly that reason.
+report() {
+    if [[ "${CRATIS_HOOKS_SUBPATH_REPORT:-0}" == "1" ]]; then printf 'ai-corpus subpath: %s\n' "$1" >&2; fi
+}
+
+# Tier 3 over the same roots: whether the .NET types the corpus names in prose and in C# positions
+# exist at all. Invoked exactly like Tier 2 at the bottom of this file — tested with -f, not -x, and
+# run through `bash`, so a checkout that lost the exec bit does not silently drop the guard — but
+# necessarily *above* the two gates below, because it reads a NuGet cache rather than node_modules
+# and must still run in a repository that has no frontend and no `jq`.
+types="$(dirname "${BASH_SOURCE[0]}")/validate-type-references.sh"
+if [[ -f "$types" ]]; then bash "$types" "$@" || true; fi
+
+command -v jq >/dev/null 2>&1 || exit 0
+[[ -d node_modules/@cratis ]] || exit 0
+
+# `.cratis/ai/hooks` is deliberately not a default root: this file and ../README.md name deliberately-bogus
+# subpaths as examples, and a guard that reports its own documentation is a guard people switch off.
+if [[ $# -gt 0 ]]; then roots=("$@"); else roots=(.cratis/ai/rules .cratis/ai/skills .cratis/ai/agents .cratis/ai/prompts); fi
+scan=()
+for d in "${roots[@]}"; do [[ -d "$d" ]] && scan+=("$d"); done
+[[ "${#scan[@]}" -gt 0 ]] || exit 0
+
+# A line that carries a version alongside the reference has already declared the skew on purpose
+# (`(**≥ 3.0.0**)`), so it is not drift. Kept deliberately generous — a dotted version, an `N.x`, or
+# either inequality spelling qualifies — because the cost of a missed warning is one stale line while
+# the cost of a false one is noise on exactly the lines someone just fixed correctly.
+version_re='[0-9]+\.[0-9x]+|≥|>='
+
+# `node_modules/@cratis/...` in the corpus is a filesystem path (a "look in the .d.ts" pointer), not a
+# module specifier. Capture the prefix so it can be dropped rather than mis-parsed as a subpath.
+refs="$(grep -rhoE '(node_modules/)?@cratis/[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)+' "${scan[@]}" 2>/dev/null \
+    | grep -v '^node_modules/' | sed -E 's/[.-]+$//' | LC_ALL=C sort -u || true)"
+[[ -n "$refs" ]] || exit 0
+
+# Prints yes | no | unknown for "./<subpath>" against a package.json's exports map. `unknown` covers
+# every shape that carries no authoritative subpath list; only `no` is ever reported.
+resolves() {
+    jq -r --arg s "./$2" '
+        def matches($key): if ($key | contains("*"))
+            then ($key | split("*")) as $p
+                | if ($p | length) == 2 then ($s | startswith($p[0])) and ($s | endswith($p[1])) else true end
+            else $key == $s end;
+        (.exports // null) as $e
+        | if $e == null then "unknown"
+          elif ($e | type) == "string" then "no"
+          elif ($e | type) != "object" then "unknown"
+          else ($e | keys) as $k
+            | if ([$k[] | startswith(".")] | any) == false then "no"
+              elif ([$k[] | select(matches(.))] | length) > 0 then "yes"
+              else "no" end
+          end' "$1" 2>/dev/null || printf 'unknown'
+}
+
+printf '%s\n' "$refs" | while IFS= read -r ref; do
+    [[ -n "$ref" ]] || continue
+    rest="${ref#@cratis/}"; pkg="${rest%%/*}"; sub="${rest#*/}"
+    manifest="node_modules/@cratis/$pkg/package.json"
+    if [[ ! -f "$manifest" ]]; then report "$ref — skipped (@cratis/$pkg not installed)"; continue; fi
+    status="$(resolves "$manifest" "$sub")"
+    version="$(jq -r '.version // "?"' "$manifest" 2>/dev/null || printf '?')"
+    if [[ "$status" != "no" ]]; then report "$ref — $status (@cratis/$pkg $version)"; continue; fi
+
+    # Bounded so `.../CommandForm` does not answer for `.../CommandForm/fields`. Qualification is
+    # judged per (file, reference): the corpus states a subpath's version requirement once and may
+    # then mention it again unqualified in the same file, so any qualified line clears the file.
+    bounded="($(printf '%s' "$ref" | sed 's/\./\\./g'))([^A-Za-z0-9._/-]|\$)"
+    { grep -rlE "$bounded" "${scan[@]}" 2>/dev/null || true; } | LC_ALL=C sort | while IFS= read -r file; do
+        # `grep -n` prefixes each hit with `<line>:`, which carries no dot and so cannot itself look
+        # like a version. Lines where the reference is part of a node_modules path are dropped again
+        # here — the extraction pass already ignores them, and they are not module specifiers.
+        hits="$(grep -nE "$bounded" "$file" 2>/dev/null | grep -vF "node_modules/$ref" || true)"
+        [[ -n "$hits" ]] || continue
+        # A here-string, never `printf … | grep -q`: an early-exiting `grep -q` closes the pipe,
+        # `printf` dies of SIGPIPE with 141, and under `pipefail` the pipeline reports failure even
+        # though the version matched — turning a correctly-qualified line into a warning.
+        if grep -qE "$version_re" <<<"$hits"; then
+            report "$ref — missing from @cratis/$pkg $version but version-qualified in $file"
+            continue
+        fi
+        line="$(printf '%s\n' "$hits" | head -1 | cut -d: -f1)"
+        warn "$file:$line: '$ref' is not in the exports map of the installed @cratis/$pkg $version — fix the reference, or mark the line with the version it needs (e.g. '(≥ 3.0.0)')"
+    done
+done
+
+# Tier 2 over the same roots: a subpath that resolves says nothing about the *names* imported
+# through it. Kept in its own script — a different question, a different corpus extraction and a
+# different report variable — and invoked from here so the single call site in validate-ai-setup.sh
+# gets both. Tested with -f, not -x, and run through `bash`: a checkout that lost the exec bit must
+# not silently drop the guard.
+imports="$(dirname "${BASH_SOURCE[0]}")/validate-package-imports.sh"
+if [[ -f "$imports" ]]; then bash "$imports" "$@" || true; fi