#!/usr/bin/env bats # construct-index.bats — pins the construct-index generator (effected#188): the # committed constructs/ tables are exactly what regeneration from the doc # models + annotations produces, and every value-kind export carries an intent # annotation (strictness phased in; see the strict test below). PLUGIN_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)" REPO_ROOT="$(cd "$PLUGIN_ROOT/.." && pwd)" GEN="$PLUGIN_ROOT/scripts/generate-constructs.mts" FIXTURES="$PLUGIN_ROOT/__test__/fixtures" setup_file() { # CI's shell-tests job runs this suite on a fresh checkout with no dist/ # artifacts. Generator exit 2 is the missing-doc-model signal and 3 the # stale-doc-model one (src/ newer than the model) — provision them # ourselves; turbo's remote cache makes the build cheap there. Exit 0/1 # (ok / annotation problems) need no build. local status=0 node "$GEN" check >/dev/null 2>&1 || status=$? if [ "$status" -eq 2 ] || [ "$status" -eq 3 ]; then echo "# doc models missing or stale — running pnpm build to provision them" >&3 (cd "$REPO_ROOT" && pnpm build) >&2 || return 1 fi } @test "fixture: generate renders one table per package with merged kinds, escaped pipes, and cross-links" { out="$BATS_TEST_TMPDIR/constructs" run node "$GEN" generate \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" \ --out "$out" [ "$status" -eq 0 ] [ -f "$out/demo.md" ] [ -f "$out/impl.md" ] # generated header present grep -q "GENERATED by plugin/scripts/generate-constructs.mts" "$out/demo.md" # TSDoc summary extracted, first paragraph only, no @example bleed grep -q "A document's standing against the NTIA minimum elements." "$out/demo.md" ! grep -q "@example" "$out/demo.md" # merged Variable+Interface renders one row with both kinds. -F, not a BRE: # GNU grep reads \` as the start-of-buffer anchor, so the escaped-backtick # spelling matched on BSD grep and could never match in CI. [ "$(grep -cF '| `IdentityToken` |' "$out/demo.md")" -eq 1 ] grep -q "Variable + Interface" "$out/demo.md" # pipe in a docComment is escaped so the table row survives grep -qF "report's \\|" "$out/demo.md" # a literal backslash-pipe in source escapes backslash-first, so no bare # delimiter leaks into the cell (CodeQL: incomplete string escaping) grep -qF 'and \\\| backslash-pipe' "$out/demo.md" # intent column filled from annotations grep -q "validate NTIA minimum elements" "$out/demo.md" # cross-link: impl side names the contract... grep -q 'implements `IdentityToken` from `@effected/demo`' "$out/impl.md" # ...and the contract side names the implementation (derived by inversion) grep -q 'implemented by `OidcTokenIssuer` in `@effected/impl`' "$out/demo.md" # subpath-only entry point construct gets a derived from-package qualifier grep -qF 'from `@effected/demo/sub`' "$out/demo.md" } @test "fixture: a forgotten export (~ in canonicalReference) or a class-factory _base is neither rendered nor demanded an intent" { out="$BATS_TEST_TMPDIR/constructs" run node "$GEN" generate \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" \ --out "$out" [ "$status" -eq 0 ] # the private brand symbol carries `@effected/demo!~HiddenBrand:var`; the # class-factory base is dropped on its name even when this doc-model # vintage did not mark it forgotten. Neither is importable, so neither is a row ! grep -qF 'NtiaReport_base' "$out/demo.md" ! grep -qF 'HiddenBrand' "$out/demo.md" # an exported symbol carrying a plain reference still renders grep -qF '| `renderReport` |' "$out/demo.md" # and the strict check does not name either forgotten symbol run node "$GEN" check --require-intent \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" [[ "$output" != *"NtiaReport_base"* ]] [[ "$output" != *"HiddenBrand"* ]] } @test "fixture: generate exits 2 naming the package when a doc model is missing" { broken="$BATS_TEST_TMPDIR/broken" mkdir -p "$broken/packages/ghost" printf '{"name":"@effected/ghost","version":"0.0.0","private":true}\n' > "$broken/packages/ghost/package.json" run node "$GEN" generate \ --packages "$broken/packages" \ --annotations "$FIXTURES/constructs-annotations.json" \ --out "$BATS_TEST_TMPDIR/out2" [ "$status" -eq 2 ] [[ "$output" == *"build first"* ]] [[ "$output" == *"ghost"* ]] } @test "fixture: check passes without --require-intent when annotations are merely incomplete" { run node "$GEN" check \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" [ "$status" -eq 0 ] } @test "fixture: check --require-intent fails naming each unannotated value construct" { run node "$GEN" check \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" \ --require-intent [ "$status" -eq 1 ] # renderReport is a Function with no annotation in the fixture [[ "$output" == *"missing intent annotation: demo.renderReport"* ]] # ReportShape is a TypeAlias — must NOT be required [[ "$output" != *"ReportShape"* ]] } @test "fixture: check fails on a stale annotation naming a construct that no longer exists" { stale="$BATS_TEST_TMPDIR/stale.json" printf '{"demo":{"Departed":"gone construct"}}\n' > "$stale" run node "$GEN" check \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$stale" [ "$status" -eq 1 ] [[ "$output" == *"stale annotation: demo.Departed"* ]] } @test "fixture: check --require-intent treats a blank intent as missing" { blank="$BATS_TEST_TMPDIR/blank.json" printf '{"demo":{"renderReport":" "}}\n' > "$blank" run node "$GEN" check \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$blank" \ --require-intent [ "$status" -eq 1 ] [[ "$output" == *"missing intent annotation: demo.renderReport"* ]] } @test "fixture: check --require-intent fails naming SubThing when its annotation is missing" { missing="$BATS_TEST_TMPDIR/missing-subthing.json" printf '{"demo":{"NtiaReport":"validate NTIA minimum elements","IdentityToken":{"intent":"contract for minting an identity token"}}}\n' > "$missing" run node "$GEN" check \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$missing" \ --require-intent [ "$status" -eq 1 ] [[ "$output" == *"missing intent annotation: demo.SubThing"* ]] } @test "fixture: check fails on a dangling implements target" { dangling="$BATS_TEST_TMPDIR/dangling.json" printf '{"demo":{"NtiaReport":{"intent":"validate NTIA minimum elements","implements":"demo.DoesNotExist"}}}\n' > "$dangling" run node "$GEN" check \ --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$dangling" [ "$status" -eq 1 ] [[ "$output" == *"dangling implements: demo.NtiaReport -> demo.DoesNotExist"* ]] } # --- staleness guard and --only (effected#839) ------------------------------ # A doc model is stale when a file under its package's src/ is newer than it. # Each test works on a private copy of the fixture tree, with a src/ file per # package dated before its model (fresh), and ages a model to make it stale. # `touch -t` takes local time; noon keeps the UTC date on 2020-01-01 in any # timezone. _copy_fixture_repo() { repo="$BATS_TEST_TMPDIR/repo" cp -R "$FIXTURES/constructs-repo" "$repo" local pkg for pkg in demo impl; do mkdir -p "$repo/packages/$pkg/src" printf 'export {};\n' > "$repo/packages/$pkg/src/index.ts" touch -t 201901011200 "$repo/packages/$pkg/src/index.ts" done } _age_model() { # $1 = package: its model now predates its src/ touch -t 202001011200 "$repo/packages/$1/dist/prod/npm/meta/$1.api.json" touch "$repo/packages/$1/src/index.ts" } @test "staleness positive control: models newer than their src/ generate and check cleanly" { _copy_fixture_repo run node "$GEN" generate --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$BATS_TEST_TMPDIR/out" [ "$status" -eq 0 ] [ -f "$BATS_TEST_TMPDIR/out/demo.md" ] run node "$GEN" check --packages "$repo/packages" --annotations "$FIXTURES/constructs-annotations.json" [ "$status" -eq 0 ] } @test "staleness: a src/ file newer than the doc model fails generate with exit 3, naming the package, both timestamps and the build" { _copy_fixture_repo _age_model impl out="$BATS_TEST_TMPDIR/out" run node "$GEN" generate --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$out" [ "$status" -eq 3 ] [[ "$output" == *"stale doc model"* ]] [[ "$output" == *"impl: model built 2020-01-01T"* ]] [[ "$output" == *"src/index.ts modified 20"* ]] [[ "$output" == *"pnpm build --filter @effected/impl"* ]] # only the stale package is named, and nothing was written [[ "$output" != *" demo:"* ]] [ ! -e "$out" ] } @test "staleness: check fails with exit 3 on a stale doc model too" { _copy_fixture_repo _age_model impl run node "$GEN" check --packages "$repo/packages" --annotations "$FIXTURES/constructs-annotations.json" [ "$status" -eq 3 ] [[ "$output" == *"impl: model built 2020-01-01T"* ]] } @test "--only: regenerates only the named package, leaving every other table byte-identical even when its model is stale" { _copy_fixture_repo _age_model impl out="$BATS_TEST_TMPDIR/out" mkdir -p "$out" printf 'sentinel: committed impl table\n' > "$out/impl.md" cp "$out/impl.md" "$BATS_TEST_TMPDIR/impl.before" run node "$GEN" generate --only demo --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$out" [ "$status" -eq 0 ] # the stale impl model was never read, and its table was never touched cmp "$out/impl.md" "$BATS_TEST_TMPDIR/impl.before" # demo was regenerated, cross-link to impl intact (derived from annotations) grep -q 'implemented by `OidcTokenIssuer` in `@effected/impl`' "$out/demo.md" [ "$(ls "$out" | wc -l | tr -d ' ')" -eq 2 ] } @test "--only: the negative half — without it the same tree fails on the stale package" { _copy_fixture_repo _age_model impl run node "$GEN" generate --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$BATS_TEST_TMPDIR/out" [ "$status" -eq 3 ] [[ "$output" == *"--only "* ]] } @test "--only: accepts npm names and comma lists" { _copy_fixture_repo out="$BATS_TEST_TMPDIR/out" run node "$GEN" generate --only @effected/demo,impl --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$out" [ "$status" -eq 0 ] [ -f "$out/demo.md" ] [ -f "$out/impl.md" ] } @test "--only: an unknown package or a missing list is a usage error naming it" { run node "$GEN" generate --only ghost --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$BATS_TEST_TMPDIR/out" [ "$status" -eq 1 ] [[ "$output" == *"--only names no package"*"ghost"* ]] run node "$GEN" generate --only --packages "$FIXTURES/constructs-repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" --out "$BATS_TEST_TMPDIR/out" [ "$status" -eq 1 ] [[ "$output" == *"--only needs"* ]] } @test "check --only: also reads (and guards) the packages its implements links target" { _copy_fixture_repo _age_model demo # impl.OidcTokenIssuer implements demo.IdentityToken, so checking impl # must read demo's model — and a stale one fails rather than misjudging run node "$GEN" check --only impl --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" [ "$status" -eq 3 ] [[ "$output" == *"demo: model built 2020-01-01T"* ]] # demo's annotations link nowhere, so checking demo alone ignores stale impl touch "$repo/packages/demo/dist/prod/npm/meta/demo.api.json" _age_model impl run node "$GEN" check --only demo --packages "$repo/packages" \ --annotations "$FIXTURES/constructs-annotations.json" [ "$status" -eq 0 ] } @test "repo: committed constructs/ is exactly what regeneration produces" { committed="$PLUGIN_ROOT/skills/effected-packages/references/constructs" regenerated="$BATS_TEST_TMPDIR/regenerated" run node "$GEN" generate --out "$regenerated" if [ "$status" -eq 2 ] || [ "$status" -eq 3 ]; then echo "doc models missing or stale — run \`pnpm build\` before this suite" >&2 echo "$output" >&2 return 1 fi [ "$status" -eq 0 ] run diff -ru "$committed" "$regenerated" if [ "$status" -ne 0 ]; then echo "constructs/ has drifted from the doc models + annotations:" >&2 echo "$output" >&2 echo "" >&2 echo "run: node plugin/scripts/generate-constructs.mts generate — and commit the result" >&2 return 1 fi } @test "repo: annotations are complete — every value-kind construct has intent, none are stale" { run node "$GEN" check --require-intent [ "$status" -eq 0 ] }