MicrosoftLearning
diff --git a/‎.github/workflows/content-checks.yml‎
Lines changed: 52 additions & 0 deletions b/‎.github/workflows/content-checks.yml‎
Lines changed: 52 additions & 0 deletions
diff --git a/‎.github/workflows/sdk-contract.yml‎
Lines changed: 117 additions & 0 deletions b/‎.github/workflows/sdk-contract.yml‎
Lines changed: 117 additions & 0 deletions
diff --git a/‎tools/checks/README.md‎
Lines changed: 98 additions & 0 deletions b/‎tools/checks/README.md‎
Lines changed: 98 additions & 0 deletions
diff --git a/‎tools/checks/check_code_blocks.py‎
Lines changed: 81 additions & 0 deletions b/‎tools/checks/check_code_blocks.py‎
Lines changed: 81 additions & 0 deletions
@@ -0,0 +1,52 @@
+name: Content checks
+
+# Tier 0: fast, static checks that need no Azure resources and no credentials.
+# These catch the failure modes that actually reach learners - a code block that
+# won't parse, frontmatter that breaks the site build, a link to a page that was
+# renamed, or line endings drifting back to CRLF.
+
+on:
+  # No path filter: the whole suite takes about ten seconds, and filtering
+  # only creates blind spots. A change to _includes or a root markdown file
+  # can break every lab page, so it should be checked too.
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  content-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          # Matches what the labs tell learners to install ("Python 3.13 or
+          # later") and what they are tested against. Testing on anything else
+          # risks passing on a configuration no learner uses.
+          python-version: "3.13"
+
+      - name: Install check dependencies
+        run: pip install --disable-pip-version-check -r tools/checks/requirements.txt
+
+      # Each check runs as its own step so a failure is obvious in the UI, and
+      # always() means one failing check doesn't hide the others.
+      - name: Frontmatter is valid
+        if: always()
+        run: python tools/checks/check_frontmatter.py
+
+      - name: Python code blocks parse
+        if: always()
+        run: python tools/checks/check_code_blocks.py
+
+      - name: Links and media resolve
+        if: always()
+        run: python tools/checks/check_links.py
+
+      - name: Line endings match .gitattributes
+        if: always()
+        run: python tools/checks/check_line_endings.py
@@ -0,0 +1,117 @@
+name: SDK contract
+
+# Tier 1: install each lab's pinned requirements, import the modules the lab
+# ships, and assert the SDK symbols and keyword arguments the instructions use
+# still exist.
+#
+# No Azure resources, no credentials, no spend - so this can run nightly and
+# give early warning before a learner hits a broken lab.
+#
+# It runs twice per lab:
+#   pinned  - the versions in requirements.txt. A failure means something was
+#             yanked or a transitive dependency broke.
+#   latest  - unpinned. A failure is early warning for the next version bump,
+#             so it does not fail the job.
+
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  pull_request:
+    paths:
+      - "Labfiles/**/requirements.txt"
+      - "tools/checks/check_sdk_contract.py"
+      - ".github/workflows/sdk-contract.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  discover:
+    runs-on: ubuntu-latest
+    outputs:
+      labs: ${{ steps.list.outputs.labs }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - id: list
+        run: |
+          labs=$(python tools/checks/check_sdk_contract.py --list | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          echo "labs=$labs" >> "$GITHUB_OUTPUT"
+
+  contract:
+    needs: discover
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        lab: ${{ fromJSON(needs.discover.outputs.labs) }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          # Matches what the labs tell learners to install ("Python 3.13 or
+          # later") and what they are tested against. Testing on anything else
+          # risks passing on a configuration no learner uses.
+          python-version: "3.13"
+
+      - name: Install pinned requirements
+        run: |
+          pip install --disable-pip-version-check -r tools/checks/requirements.txt
+          pip install --disable-pip-version-check -r "Labfiles/${{ matrix.lab }}/Python/requirements.txt"
+
+      - name: Check SDK contract (pinned)
+        run: python tools/checks/check_sdk_contract.py --lab "${{ matrix.lab }}"
+
+      - name: Check SDK contract (latest, advisory)
+        continue-on-error: true
+        run: |
+          sed -E 's/[=<>~!]=.*//' "Labfiles/${{ matrix.lab }}/Python/requirements.txt" > /tmp/latest.txt
+          pip install --disable-pip-version-check --upgrade -r /tmp/latest.txt
+          python tools/checks/check_sdk_contract.py --lab "${{ matrix.lab }}"
+
+  report:
+    needs: contract
+    if: failure() && github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      # These labs are maintained asynchronously, so a red badge nobody is
+      # watching is worth nothing. Open an issue instead.
+      - name: Open an issue for the failure
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = 'SDK contract check failed';
+            const url = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'sdk-contract',
+            });
+            if (existing.data.length > 0) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.data[0].number,
+                body: `Nightly SDK contract check failed again: ${url}`,
+              });
+              return;
+            }
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title,
+              labels: ['sdk-contract'],
+              body: [
+                'The nightly SDK contract check failed, which usually means a',
+                'package the labs depend on changed an import path or a keyword',
+                'argument.',
+                '',
+                `Run: ${url}`,
+              ].join('\n'),
+            });
@@ -0,0 +1,98 @@
+# Lab content checks
+
+Automated checks that catch problems in the lab content before a learner hits
+them. They are deliberately cheap: **no Azure resources, no credentials, and no
+spend**, so they can run on every pull request.
+
+## Running them locally
+
+```
+pip install -r tools/checks/requirements.txt
+python tools/checks/check_frontmatter.py
+python tools/checks/check_code_blocks.py
+python tools/checks/check_links.py
+python tools/checks/check_line_endings.py
+```
+
+Each script exits non-zero when it finds a problem and prints the file and line.
+In GitHub Actions the same output becomes an inline annotation on the pull
+request diff.
+
+## Tier 0 — content checks (every pull request, and every push to `main`)
+
+| Check | What it catches |
+| --- | --- |
+| `check_frontmatter.py` | YAML that won't parse, which breaks the site build. The usual cause is an unescaped apostrophe inside a single-quoted value, such as `verify: 'you don't have access'`. |
+| `check_code_blocks.py` | A ```` ```python ```` block that isn't valid Python. Learners paste these straight into a file, so a bad indent breaks the lab. |
+| `check_links.py` | A link to a page that was renamed or moved, or a screenshot that no longer exists. |
+| `check_line_endings.py` | Text files drifting back to CRLF in the index, against the `.gitattributes` policy. |
+
+### Why the code block check normalizes first
+
+The blocks are snippets, not programs, so parsing them as-is is useless — 134 of
+148 blocks in this repo would report a false positive. The check therefore:
+
+1. **Dedents** the block, because snippets are indented to sit inside a function
+   body.
+2. **Closes a trailing open block** if parsing failed *only* because a `with` or
+   `def` has no body — the lab adds that body in a later step.
+
+A genuine syntax error — a typo, an unbalanced bracket, or a bad indent *within*
+the snippet — still fails. That is the class of bug behind the `fix fence
+indentation` and `fix code sample indentation` fixes on `main`.
+
+## Tier 1 — SDK contract (nightly)
+
+`check_sdk_contract.py` installs each lab's pinned requirements, then checks that
+every module and symbol the lab imports still resolves — both in the Python
+files the lab ships **and in the code blocks the instructions tell learners to
+paste**.
+
+It runs nightly, and on any pull request that touches a `requirements.txt`, the
+check itself, or its workflow — the changes most likely to break it. It is
+path-filtered because it installs dependencies across a matrix of every lab,
+which is too slow to run on unrelated pull requests.
+
+This targets the breakages this repo actually hits, which are import- and
+signature-level:
+
+- *Fix Exercise 3: Update FastMCP import to standalone package*
+- *Update labs 02 and 03 to `azure-ai-projects==2.0.0b4`*
+- *Revert agent-framework bump on legacy labs 07/08*
+
+Each would have been caught here, without any Azure resources, before reaching a
+learner.
+
+It runs twice per lab. **Pinned** uses the versions in `requirements.txt`; a
+failure means something was yanked or a transitive dependency broke. **Latest**
+strips the pins; a failure there is early warning for the next version bump and
+does not fail the job.
+
+Because these labs are maintained asynchronously, a scheduled failure opens a
+GitHub issue rather than relying on someone noticing a red badge.
+
+### The import contract maintains itself
+
+There is no hand-written list of expected symbols. The contract is derived from
+the content, so it cannot drift: add an import to a lab or an instruction code
+block and it is checked automatically.
+
+Only **keyword arguments** are pinned by hand, in `KWARG_CONTRACTS`, because
+they can't be derived reliably. If you change a code block to pass a new
+argument, add it there so a future SDK rename fails loudly instead of silently
+breaking the lab.
+
+Starter files are expected to be incomplete — a `def` whose body the learner
+fills in later is a syntax error by design — so a parse failure with that
+signature is ignored outside `Solution/`.
+
+## Not yet covered
+
+These need groundwork that doesn't exist yet:
+
+| Check | Blocked on |
+| --- | --- |
+| Strict frontmatter schema (`type`, `section`, `difficulty`, `order`) | The consolidated labs carrying that metadata. |
+| Generated task tables match frontmatter | The same metadata, plus the table include. |
+| Instructions match the `Solution/` code | A convention for mapping a code block to its solution file, e.g. an HTML comment above each block. |
+| Shared infrastructure hasn't drifted between labs | A canonical `Labfiles/_shared/` with a sync script. |
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Check that every ```python block in the lab instructions is valid Python.
+
+Learners paste these blocks straight into a file, so a syntax error - almost
+always a bad indent - breaks the lab. Two fixes on main ("fix fence
+indentation", "fix code sample indentation") were exactly this class of bug.
+
+Normalization matters here. The blocks are snippets, not programs:
+
+  1. They are indented to sit inside a function body, so the whole block is
+     dedented first. Without this, 134 of 148 blocks would report false
+     positives.
+  2. Some intentionally end on an open block - a `with` or `def` whose body the
+     lab adds in a later step. If parsing fails *only* because a block opener
+     has no body, a `pass` is appended and it is retried.
+
+A genuine syntax error - typo, unbalanced bracket, or bad indent *within* the
+snippet - still fails, which is the point.
+"""
+
+import ast
+import re
+import textwrap
+
+from common import Reporter, lab_pages, main_guard
+
+FENCE = re.compile(r"(?ms)^[ \t]*```python[ \t]*\r?\n(.*?)^[ \t]*```")
+INCOMPLETE_BLOCK = "expected an indented block"
+
+
+def close_open_block(code: str) -> str:
+    """Give a trailing block opener a body so a fragment can be parsed."""
+    lines = [l for l in code.rstrip().split("\n") if l.strip()]
+    if not lines:
+        return code
+    last = lines[-1]
+    indent = len(last) - len(last.lstrip())
+    if last.rstrip().endswith(":"):
+        indent += 4
+    return code.rstrip() + "\n" + " " * indent + "pass\n"
+
+
+def parse_snippet(code: str):
+    """Return None if the snippet is acceptable, else a SyntaxError to report."""
+    dedented = textwrap.dedent(code)
+    try:
+        ast.parse(dedented)
+        return None
+    except SyntaxError as first:
+        if INCOMPLETE_BLOCK not in str(first):
+            return first
+
+    try:
+        ast.parse(close_open_block(dedented))
+        return None
+    except SyntaxError as second:
+        return second
+
+
+def check() -> int:
+    r = Reporter("python code blocks")
+
+    for path in lab_pages():
+        text = path.read_text(encoding="utf-8")
+        for match in FENCE.finditer(text):
+            r.checked += 1
+            err = parse_snippet(match.group(1))
+            if err is None:
+                continue
+
+            # Line of the ``` fence, plus the offset reported inside the block.
+            fence_line = text[: match.start()].count("\n") + 1
+            line = fence_line + (err.lineno or 1)
+            reason = str(err).split("(")[0].strip()
+            r.add(path, f"invalid Python in code block: {reason}", line)
+
+    return r.finish("blocks")
+
+
+if __name__ == "__main__":
+    main_guard(check)