From 7fbbf891cbee4e9e5aa407eebd1b26a4cb8d4c37 Mon Sep 17 00:00:00 2001 From: Andrew Bartels Date: Sat, 14 Nov 2026 19:43:31 -0800 Subject: [PATCH 1/4] chore(openspec): archive honest-tool-list; queue item 10 done (#229) The drawing-pack plan keeps the new 'After the clean-up' scenario, now saying no tool is planned once the drawing pack is built. --- .../.openspec.yaml | 0 .../2026-11-14-honest-tool-list}/design.md | 0 .../2026-11-14-honest-tool-list}/proposal.md | 0 .../specs/tools/document-inspection/spec.md | 0 .../specs/tools/file-saving/spec.md | 0 .../specs/tools/support-levels/spec.md | 0 .../specs/tools/tool-deprecation/spec.md | 0 .../specs/tools/tool-naming/spec.md | 0 .../2026-11-14-honest-tool-list}/tasks.md | 2 +- .../specs/tools/support-levels/spec.md | 4 +- openspec/queue.md | 2 +- .../specs/tools/document-inspection/spec.md | 17 +++++++- openspec/specs/tools/file-saving/spec.md | 21 ++++++++++ openspec/specs/tools/support-levels/spec.md | 14 +++++-- openspec/specs/tools/tool-deprecation/spec.md | 42 +++++++++++++++++++ openspec/specs/tools/tool-naming/spec.md | 34 +++++++++++++++ 16 files changed, 128 insertions(+), 8 deletions(-) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/.openspec.yaml (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/design.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/proposal.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/specs/tools/document-inspection/spec.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/specs/tools/file-saving/spec.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/specs/tools/support-levels/spec.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/specs/tools/tool-deprecation/spec.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/specs/tools/tool-naming/spec.md (100%) rename openspec/changes/{honest-tool-list => archive/2026-11-14-honest-tool-list}/tasks.md (98%) create mode 100644 openspec/specs/tools/tool-deprecation/spec.md create mode 100644 openspec/specs/tools/tool-naming/spec.md diff --git a/openspec/changes/honest-tool-list/.openspec.yaml b/openspec/changes/archive/2026-11-14-honest-tool-list/.openspec.yaml similarity index 100% rename from openspec/changes/honest-tool-list/.openspec.yaml rename to openspec/changes/archive/2026-11-14-honest-tool-list/.openspec.yaml diff --git a/openspec/changes/honest-tool-list/design.md b/openspec/changes/archive/2026-11-14-honest-tool-list/design.md similarity index 100% rename from openspec/changes/honest-tool-list/design.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/design.md diff --git a/openspec/changes/honest-tool-list/proposal.md b/openspec/changes/archive/2026-11-14-honest-tool-list/proposal.md similarity index 100% rename from openspec/changes/honest-tool-list/proposal.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/proposal.md diff --git a/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md b/openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/document-inspection/spec.md similarity index 100% rename from openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/document-inspection/spec.md diff --git a/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md b/openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/file-saving/spec.md similarity index 100% rename from openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/file-saving/spec.md diff --git a/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md b/openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/support-levels/spec.md similarity index 100% rename from openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/support-levels/spec.md diff --git a/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md b/openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/tool-deprecation/spec.md similarity index 100% rename from openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/tool-deprecation/spec.md diff --git a/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md b/openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/tool-naming/spec.md similarity index 100% rename from openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/specs/tools/tool-naming/spec.md diff --git a/openspec/changes/honest-tool-list/tasks.md b/openspec/changes/archive/2026-11-14-honest-tool-list/tasks.md similarity index 98% rename from openspec/changes/honest-tool-list/tasks.md rename to openspec/changes/archive/2026-11-14-honest-tool-list/tasks.md index 56d423bb..b1514919 100644 --- a/openspec/changes/honest-tool-list/tasks.md +++ b/openspec/changes/archive/2026-11-14-honest-tool-list/tasks.md @@ -45,4 +45,4 @@ ## 8. Finish - [x] 8.1 Full mock suite at 100% coverage, ruff, `mkdocs build --strict` -- [ ] 8.2 Sign-off, PR (no attribution) closing #174, archive, the queue updated +- [x] 8.2 Sign-off, PR (no attribution) closing #174, archive, the queue updated diff --git a/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md b/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md index 9286d12f..2956be08 100644 --- a/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md +++ b/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md @@ -12,6 +12,6 @@ The check SHALL fail when a level contradicts what the code shows. A `planned` t - **WHEN** a tool is `stable` - **THEN** at least one test under `tests/live/` calls it by name -#### Scenario: After the drawing pack +#### Scenario: After the clean-up - **WHEN** the levels are counted after this change -- **THEN** no tool is `planned` +- **THEN** no tool is `planned`: the seven drawing tools the honest tool list left planned are built diff --git a/openspec/queue.md b/openspec/queue.md index 1575392a..42d965ed 100644 --- a/openspec/queue.md +++ b/openspec/queue.md @@ -20,7 +20,7 @@ Last updated 2026-11-14. | 7 | Beta tools to stable: fix each beta tool's known fault (the small faults listed below), prove it live, and move it up a level | not filed yet | `beta-tool-faults` (archived) | Done 2026-11-09 (#219, 2.0.0): 23 tools promoted, signed off live | | 8 | Experimental tools to stable: a live test for each of the 10, then promote it or record its fault | not filed yet | `experimental-tools-to-stable` (archived) | Done 2026-11-12 (2.0.0, tagged `v2.0.0`): all 10 promoted, signed off live. Pack and Go now copies the files `GetDependencies2` lists (SolidWorks 2026's own Pack and Go copied only the assembly); `comtypes` dropped | | 9 | Monitor stand demo follow-ups: feature order, `verify_model`'s planes, dimension listing, STL export, `create_sketch` on a face, the demo's camera | #206 | `monitor-stand-follow-ups` (archived) | Done 2026-11-14: all five live tests pass, GIF re-recorded; PR open | -| 10 | An honest tool list: remove the 33 planned tools no item will build (the design table among them, after its live check), deprecate the stable duplicates for one release, settle a verb list. Replaces the old items "the 40 planned tools" and "duplicate tools" | #174 | `honest-tool-list` | Planned 2026-11-12. Items 11-14 depend on it. It probes `manage_design_table` live before removing it (kept for item 13 if design tables work) | +| 10 | An honest tool list: remove the 33 planned tools no item will build (the design table among them, after its live check), deprecate the stable duplicates for one release, settle a verb list. Replaces the old items "the 40 planned tools" and "duplicate tools" | #174 | `honest-tool-list` (archived) | Done 2026-11-14 (#229): 33 removed (the design table after its live check failed), 8 deprecated until 3.0.0, the verb list. Items 11-14 can start | | 19 | Our own `llms.txt`, and every link checked. A script builds `llms.txt` from the mkdocs nav: each entry's title and summary are copied word for word from the page they link to, and nothing is written by hand. A check follows EVERY link in `llms.txt`, the README and the docs (internal pages, anchors and external URLs), and fails on a dead link, a redirect off this repo, or an `llms.txt` line that doesn't match its page. Security review of the result: only this repo's own pages, no third-party links, no hidden text or instructions. PR #225's file is not used as a starting point; the user is closing that PR | #225 (closed, not merged) | not yet written | Added 2026-11-14 at the user's request. Next after item 10, so the file lists only working tools | | 11 | Part features the peers lead with: Hole Wizard holes, cosmetic threads, a linear feature pattern, shell, draft, rib, and sketch convert-entities | #105 | `part-feature-depth` | Planned 2026-11-12 | | 12 | The drawing pack, where no peer goes: section and detail views, the title block and sheet format, drawing dimensions, and one drawing check | #102, #158 | `drawing-pack` | Planned 2026-11-12. Builds the 7 planned drawing tools item 10 leaves | diff --git a/openspec/specs/tools/document-inspection/spec.md b/openspec/specs/tools/document-inspection/spec.md index eaddb6c0..94fe0629 100644 --- a/openspec/specs/tools/document-inspection/spec.md +++ b/openspec/specs/tools/document-inspection/spec.md @@ -2,7 +2,6 @@ ## Purpose The tools that read the active document (`get_file_properties`, `list_configurations`, `classify_feature_tree`, `load_part`, `load_assembly`) report what SolidWorks says, and fail plainly when they can't read it. - ## Requirements ### Requirement: File properties describe the active document's file @@ -53,3 +52,19 @@ SolidWorks opened, or `null` when it can't be read, never an assumed - **WHEN** an agent calls `load_assembly` with a `.sldprt` path - **THEN** the call fails with `invalid_input`, and nothing is opened +### Requirement: Model info includes the file's details +`get_model_info` SHALL report, besides what it reports today, the active +document's file size in bytes and its created and modified times, read +from the file on disk. For a document never saved, they SHALL be `null`. + +#### Scenario: A saved part +- **WHEN** a part saved to disk is active and an agent calls + `get_model_info` +- **THEN** the reply has `size_bytes` above 0 and `created` and `modified` + times, as `get_file_properties` reports them + +#### Scenario: A new, unsaved part +- **WHEN** a part never saved is active +- **THEN** `size_bytes`, `created` and `modified` are `null`, and the call + succeeds + diff --git a/openspec/specs/tools/file-saving/spec.md b/openspec/specs/tools/file-saving/spec.md index e8d29fd4..68056c0b 100644 --- a/openspec/specs/tools/file-saving/spec.md +++ b/openspec/specs/tools/file-saving/spec.md @@ -17,3 +17,24 @@ SHALL replace the file. - **WHEN** the same call has `overwrite: true` - **THEN** the file is replaced and the call succeeds +### Requirement: save_file checks a new path before writing +When `save_file` is given `file_path`, it SHALL check, before calling +SolidWorks, that the folder exists and is writable, that the extension +matches the active document's type (`.sldprt`, `.sldasm`, `.slddrw`), and +that no file is there unless `overwrite` is on. A failed check SHALL be an +`invalid_input` error that leaves the disk unchanged. + +#### Scenario: A part saved to a missing folder +- **WHEN** the active document is a part and `save_file` is called with + `C:/no/such/folder/bracket.sldprt` +- **THEN** the call fails with `invalid_input` naming the folder, and + SolidWorks is not asked to save + +#### Scenario: The wrong extension +- **WHEN** the active document is an assembly and `file_path` ends `.sldprt` +- **THEN** the call fails with `invalid_input` naming `.sldasm` + +#### Scenario: Saving in place +- **WHEN** `save_file` is called with no `file_path` +- **THEN** the document is saved to its own path, as before + diff --git a/openspec/specs/tools/support-levels/spec.md b/openspec/specs/tools/support-levels/spec.md index e1287ebb..b8cd8df3 100644 --- a/openspec/specs/tools/support-levels/spec.md +++ b/openspec/specs/tools/support-levels/spec.md @@ -5,7 +5,7 @@ TBD - created by archiving change tool-support-levels-and-progress. Update Purpo ## Requirements ### Requirement: One support level per tool -Every registered tool SHALL have exactly one support level, `stable`, `beta`, `experimental` or `planned`, recorded in one table, with a one-line reason for every level below `stable`. +Every registered tool SHALL have exactly one support level, `stable`, `beta`, `experimental`, `planned` or `deprecated`, recorded in one table, with a one-line reason for every level other than `stable`. A `deprecated` tool's reason SHALL name its replacement (or say there is none) and the version it was deprecated in. #### Scenario: A new tool without a level - **WHEN** a tool is registered that the table does not list @@ -15,18 +15,26 @@ Every registered tool SHALL have exactly one support level, `stable`, `beta`, `e - **WHEN** the table lists a name that no registered tool has - **THEN** the check fails and names it +#### Scenario: A deprecated tool without a replacement named +- **WHEN** a tool is `deprecated` and its entry names neither a registered replacement nor "no replacement" +- **THEN** the check fails and names the tool + ### Requirement: Levels are consistent with the code -The check SHALL fail when a level contradicts what the code shows. +The check SHALL fail when a level contradicts what the code shows. A `planned` tool's reason SHALL name the queue item that builds it. #### Scenario: Planned means not implemented - **WHEN** a tool is `planned` -- **THEN** its description says "Not available yet", and no tool outside `planned` says so +- **THEN** its description says "Not available yet", no tool outside `planned` says so, and its reason names a queue item #### Scenario: Stable means checked live - **WHEN** a tool is `stable` - **THEN** at least one test under `tests/live/` calls it by name +#### Scenario: After the clean-up +- **WHEN** the levels are counted after this change +- **THEN** exactly seven tools are `planned`, all drawing tools, each naming queue item 12 + ### Requirement: The level is visible to clients A tool's level SHALL be shown in its tags and, below `stable`, in its results. diff --git a/openspec/specs/tools/tool-deprecation/spec.md b/openspec/specs/tools/tool-deprecation/spec.md new file mode 100644 index 00000000..f7533215 --- /dev/null +++ b/openspec/specs/tools/tool-deprecation/spec.md @@ -0,0 +1,42 @@ +# tools/tool-deprecation Specification + +## Purpose +A tool replaced by another keeps working for one minor release, and says +what replaced it, so a client can move without breaking. +## Requirements +### Requirement: A deprecated tool keeps working and names its replacement +A tool at the `deprecated` level SHALL behave as before. Its description +SHALL open with "Deprecated: use ``." (or "Deprecated: no +replacement." when there is none), and a successful result SHALL carry that +sentence as `warning`. + +#### Scenario: Calling a deprecated tool +- **WHEN** an agent calls `load_part` with a valid part path +- **THEN** the part opens as before, and the result's `warning` is + "Deprecated: use `open_model`." + +#### Scenario: Reading its description +- **WHEN** a client lists the tools +- **THEN** `load_part`'s description starts "Deprecated: use `open_model`." + and its tags include `level:deprecated` + +### Requirement: A replacement covers what it replaces +A tool SHALL be deprecated only when its replacement accepts every input +the deprecated tool accepted, or the description names the other tool +that does the rest. + +#### Scenario: save_assembly's reference copy +- **WHEN** `save_assembly` is deprecated in favour of `save_file` +- **THEN** its description says to use `pack_and_go_assembly` for a copy + with the referenced parts + +### Requirement: Deprecated tools are removed at the next major release +The support-level check SHALL fail when the package's major version is +higher than the one a tool was deprecated in and the tool is still +registered. + +#### Scenario: Releasing 3.0.0 +- **WHEN** the version is 3.0.0 and `load_part` (deprecated in 2.1.0) is + still registered +- **THEN** the check fails and names `load_part` + diff --git a/openspec/specs/tools/tool-naming/spec.md b/openspec/specs/tools/tool-naming/spec.md new file mode 100644 index 00000000..46f6e4f1 --- /dev/null +++ b/openspec/specs/tools/tool-naming/spec.md @@ -0,0 +1,34 @@ +# tools/tool-naming Specification + +## Purpose +Tool names use one verb per meaning, so an agent can guess a tool's name +and tell two tools apart from their names alone. +## Requirements +### Requirement: One verb per meaning +A tool's name SHALL start with a verb from the list in +`docs/agents/tool-description-standard.md`: + +| Verb | Meaning | +| --- | --- | +| `create_` | makes a new document, or a new feature built from a sketch or acting on the whole body (extrusion, rib, hole, shell) | +| `add_` | adds an entity to an open sketch or a drawing, or treats edges or faces of an existing body (fillet, chamfer, draft, thread) | +| `pattern_`, `mirror_` | repeats existing features | +| `sketch_` | an operation on the open sketch's entities (offset, mirror, pattern, convert) | +| `get_` | reads one thing | +| `list_` | reads a collection | +| `set_` | changes one value | +| `open_`, `save_`, `close_`, `export_` | file operations | +| `check_`, `verify_`, `measure_`, `compare_` | read-only checks | + +Names already registered that break the list SHALL be listed as +exceptions in the same file, and the check SHALL fail on any other name +that breaks it. + +#### Scenario: A new tool with an unlisted verb +- **WHEN** a tool named `make_hole` is registered +- **THEN** the naming check fails and names the tool and the verb list + +#### Scenario: An existing exception +- **WHEN** `insert_component` is registered +- **THEN** the check passes because it is a listed exception + From 6f4f5ffce5823f3374f9ecd33fe6081a7274ec19 Mon Sep 17 00:00:00 2001 From: Andrew Bartels Date: Sat, 14 Nov 2026 19:47:19 -0800 Subject: [PATCH 2/4] docs(openspec): plan own-llms-txt (queue item 19) --- openspec/changes/own-llms-txt/.openspec.yaml | 2 + openspec/changes/own-llms-txt/design.md | 188 ++++++++++++++++++ openspec/changes/own-llms-txt/proposal.md | 74 +++++++ .../specs/docs/link-check/spec.md | 53 +++++ .../own-llms-txt/specs/docs/llms-txt/spec.md | 53 +++++ openspec/changes/own-llms-txt/tasks.md | 40 ++++ openspec/queue.md | 2 +- 7 files changed, 411 insertions(+), 1 deletion(-) create mode 100644 openspec/changes/own-llms-txt/.openspec.yaml create mode 100644 openspec/changes/own-llms-txt/design.md create mode 100644 openspec/changes/own-llms-txt/proposal.md create mode 100644 openspec/changes/own-llms-txt/specs/docs/link-check/spec.md create mode 100644 openspec/changes/own-llms-txt/specs/docs/llms-txt/spec.md create mode 100644 openspec/changes/own-llms-txt/tasks.md diff --git a/openspec/changes/own-llms-txt/.openspec.yaml b/openspec/changes/own-llms-txt/.openspec.yaml new file mode 100644 index 00000000..be831cee --- /dev/null +++ b/openspec/changes/own-llms-txt/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-14 diff --git a/openspec/changes/own-llms-txt/design.md b/openspec/changes/own-llms-txt/design.md new file mode 100644 index 00000000..758a5b2b --- /dev/null +++ b/openspec/changes/own-llms-txt/design.md @@ -0,0 +1,188 @@ +## Context + +- The docs are MkDocs Material. `mkdocs.yml` has `site_url` + (`https://andrewbartels1.github.io/SolidworksMCP-python`), `repo_url`, + `site_name`, `site_description` and a hand-kept `nav` of about 60 pages + in six sections, plus `API Reference: api/` (generated by + `docs/gen_ref_pages.py`, not Markdown in `docs/`). Directory URLs are on, + so `user-guide/tools-overview.md` is served at + `/user-guide/tools-overview/`. +- `mkdocs.yml` uses `!!python/name:` tags (superfences, emoji), so a plain + `yaml.safe_load` refuses it. +- Headings get ids from Python-Markdown's `toc` extension with its default + slugify, plus explicit `{#id}` attributes (`docs/demos.md` uses them). +- The README and docs hold 116 different URLs today. Most are + `github.com/andrewbartels1/...` and the docs site; the rest are + third-party (python.org, astral.sh, shields.io badges, ollama.com, …). + Example addresses (`http://127.0.0.1:11434`, `http://YOUR-WINDOWS-IP:8000`, + `http://my-gpu-server:11434`) appear in code blocks. +- No page declares a `description:` in front matter. Most open with + `# Title` and a paragraph; some open with a list, a blockquote or a + "Last updated" line instead (`docs/index.md` opens with a feedback + blockquote and badges; `docs/planning/roadmap.md` with + "**Last updated:** …"). +- Neither `pyyaml` nor `markdown` is a runtime dependency; both come with + the `docs` extra (mkdocs). `httpx` is a runtime dependency. +- `src/solidworks_mcp/progress/` is the pattern to follow: a generator in + the package, run with `python -m`, a test that fails when its output is + stale. + +## Goals / Non-Goals + +**Goals:** + +- `llms.txt` with nothing hand-written: every title and summary traceable + to one page, word for word. +- Every link checked: within the project offline in the unit tests, and + every external URL online, with a full report. +- A file a security reviewer can read in a minute and trust: our URLs + only, no hidden characters, no HTML. + +**Non-Goals:** + +- `llms-full.txt` (every page's full text). Not asked for; the pages are + one click away. +- Front-matter `description:` fields. A summary that lives only in front + matter is invisible on the page and can drift from what the page says, + which is the problem this change exists to remove. +- Checking links in `openspec/`, `CHANGELOG.md`, source docstrings or the + skill's reference files. They aren't published as the docs site. (The + skill could come later as its own item.) +- Anything taken from PR #225. + +## Decisions + +### 1. One package, `solidworks_mcp.doc_links`, three modules and a CLI + +- `pages.py`: reads `mkdocs.yml` (a `SafeLoader` subclass that turns any + `!!python/...` tag into `None`), walks `nav`, and for each page returns + its nav section, URL, `# ` title, opening paragraph and heading ids. +- `llms_txt.py`: builds the text of `llms.txt` from the pages, and checks + a given text against it (staleness, word-for-word, allowed URLs, line + shapes, forbidden characters). +- `links.py`: finds links in Markdown (outside code), resolves internal + ones against `docs/` and the heading ids, and checks external ones + online. +- `__main__.py`: `python -m solidworks_mcp.doc_links build` writes + `docs/llms.txt`; `check` runs the offline checks; `check-external` + runs the online check and writes the report. Exit code 1 on any + failure; output through loguru. + +Alternatives: a script under `src/utils/` (not covered by the coverage +rule or the test layout); an off-the-shelf link checker such as `lychee` +or `mkdocs-htmlproofer-plugin` (one more third-party tool in the docs +pipeline, the thing this item is wary of; and neither does the +word-for-word check). The checks are small enough to own. + +### 2. The summary is the page's first prose paragraph + +The title is the page's `# ` heading; the summary is the first paragraph +after it that is prose (not a blockquote, `!!!` admonition, list, table, +fenced code, image or badge line, or HTML), stopping at the first `## `. +Links become their text (`[uv](https://…)` → `uv`), other Markdown is kept +as written, and line breaks inside the paragraph become single spaces. + +Pages that open badly (a "Last updated" line, a sentence ending in a +colon before a list) are fixed **in the page**, by giving it a real +opening paragraph, never by writing text into `llms.txt`. Task 4 reviews +every generated entry for this. + +### 3. Sections follow the nav + +Top-level pages (Home, Demos, Progress, Compatibility) go under +`## Overview`, first. Then one `## ` per nav section, its pages in nav +order; a nested section's pages are listed under their top-level section. +`API Reference: api/` is left out (it's generated Python reference, and +not a Markdown page in `docs/`). The file is `docs/llms.txt`, so MkDocs +copies it to the site root unchanged. + +### 4. What the file may contain + +- URLs: only under `site_url` or `repo_url`. Entries link to the page's + published URL. +- Characters: no Unicode category `Cf` (format: zero-width, BOM, bidi + controls) or `Cc` (control) other than `\n`; no `<` that starts a tag or + comment. +- Lines: one of `# …`, `> …`, `## …`, `- [title](url): summary`, blank. + +The builder refuses to produce a file that breaks these, naming the page; +the checker refuses a committed file that breaks them, naming the line. +The same rules on both sides mean a hand edit can't sneak past the +checker by matching a bad build. + +### 5. Offline link check in the unit tests + +An integration test runs the offline check on the real README and docs +and asserts no failures, the way the progress test does. Unit tests feed +the checker small Markdown strings. Internal links: relative paths +resolved from the linking page; links to `site_url/...` mapped back to a +page in `docs/`; files that aren't Markdown (images, GIFs) just need to +exist. README links are resolved from the repo root (they point at +`docs/...` paths or the site). + +Anchors: the ids Python-Markdown's `toc` would give (its default +slugify: NFKD-normalise, drop non-word characters, lowercase, spaces and +hyphens to one hyphen, deduplicated with `_1`, `_2` in page order), plus +`{#id}` attributes. The slugify is written in the package (a few lines) +so `markdown` isn't needed at runtime; a unit test checks it against +`markdown.extensions.toc.slugify` on every heading in the docs, skipped +when `markdown` isn't installed. + +### 6. Online check: GET, same host, retry, report + +- One `GET` per unique URL (some sites refuse `HEAD`), following + redirects, 15 s timeout, a plain `User-Agent` naming the project (no + personal details), up to 8 at a time. +- Pass: final status 2xx, and the final host equals the original with a + leading `www.` ignored. A URL under `repo_url` or `site_url` must end + under one of them. +- Retry twice on timeouts, connection resets and 429/5xx, with a short + back-off; a 4xx other than 429, or a host that doesn't resolve, fails + at once. +- A small allow-list in the package for sites known to refuse robots + (answering 403 to any script) would hide real failures, so there is + none to start with; if one turns up, it's added with a reason, and the + report still lists it as "not checked: ". +- The report is Markdown at `tests/.generated/link-report.md`: a summary + count, then a table of every URL, its result (status, or where it + redirected), and each `file:line` it appears on. In CI it is uploaded + as a workflow artifact and its failures printed to the log. + +### 7. Where the online check runs + +A new job in `deploy-docs.yml` after `deploy` (so `llms.txt` and new +pages are live before they're checked), and a weekly `schedule` trigger +(Mondays 06:00 UTC) that runs only that job. It is not in `make test` or +`dev-test`: the unit tests stay offline. `dev-commands.ps1 dev-links` +and `make links` run it by hand. + +### 8. `pyyaml` in the test and dev extras + +The package imports `yaml` at module level. `pyyaml` is added to the +`dev` and `test` extras (the `docs` extra already has it through +mkdocs). The server never imports `doc_links`, so no runtime dependency +is added. + +### 9. Security review, recorded at the end + +Task 6 reads the generated file line by line and records here: the +count of entries, that every URL is ours (the check proves it, the +review confirms it), that no summary reads as an instruction to an +agent, and the result of the first online run. + +## Risks / Trade-offs + +- **Some sites refuse scripts** (403/429 to anything without a browser + `User-Agent`), so the weekly run may fail on a link that works in a + browser → the report says which; we fix the link, switch it to a page + that answers, or add it to the allow-list with a reason (Decision 6). +- **Links break between runs** (a site moves a page midweek) → the + weekly run catches it within a week; the deploy run on every merge to + `main` catches it sooner. +- **The deploy job fails after the site is live** → it doesn't undo the + deploy, it flags a link to fix. That's the intent: a third-party page + moving shouldn't block publishing our docs. +- **Word-for-word means page edits move `llms.txt`** → the stale-file + test says which command rebuilds it, as the progress test does. +- **Our slugify drifts from Python-Markdown's** → the parity test over + every docs heading catches it wherever `markdown` is installed (CI). diff --git a/openspec/changes/own-llms-txt/proposal.md b/openspec/changes/own-llms-txt/proposal.md new file mode 100644 index 00000000..5d4241dc --- /dev/null +++ b/openspec/changes/own-llms-txt/proposal.md @@ -0,0 +1,74 @@ +## Why + +PR #225 offered an `llms.txt` written by someone we don't know. A file +like that tells agents what this project is and where to read, so whoever +writes it decides what an agent believes about the server, and a +hand-written summary drifts from the docs or carries text we never meant +to publish. The user is closing that PR. We want our own file, built from +our own pages, with nothing in it that the docs don't say. While we are +at it, nothing checks the links in the README and the docs (116 different +URLs today), so a moved page or a lapsed domain goes unnoticed. + +Queue item 19. PR #225 is not used as a starting point. + +## What Changes + +- **A generated `llms.txt`** served at the docs site's root + (`https://andrewbartels1.github.io/SolidworksMCP-python/llms.txt`). A + script builds it from the mkdocs `nav`: the site name and summary come + from `mkdocs.yml`, each section is a nav section, and each entry is a + page, linked by its published URL, with its title and summary copied + word for word from that page. Nothing in it is written by hand. +- **An offline check**, run with the unit tests and in CI, that fails + when: + - the committed `llms.txt` differs from what the script builds now; + - an `llms.txt` line's title or summary doesn't match its page word for + word (the report shows the expected and the actual text); + - `llms.txt` links anywhere but this project's own site or repository, + or holds HTML, comments, or invisible or direction-changing + characters; + - a link in the README or the docs points at a page or file that + doesn't exist, or at a heading anchor that page doesn't have. +- **An online check** that follows every external URL in `llms.txt`, the + README and the docs. It fails on a dead link, or a redirect to a + different site (a link to this repo that lands somewhere else is always + a failure). It writes a report of every link and its result. It runs + after each docs deploy and once a week, and by hand with one command; + it is not part of the unit tests, which stay offline. +- **The broken links found by the first run are fixed** in the same + change. +- A **security review** of the generated file, recorded in the design: + only this project's pages, no third-party links, no hidden text, no + instructions beyond our own page summaries. + +No tool, adapter or COM code changes. The server's behaviour is +unchanged. + +## Capabilities + +### New Capabilities + +- `docs/llms-txt`: how `llms.txt` is built from the docs and what it may + contain. +- `docs/link-check`: which links are checked, offline and online, and + what counts as a failure. + +### Modified Capabilities + +None. + +## Impact + +- New package `src/solidworks_mcp/doc_links/` (the builder, the link + finder and both checks), run as + `python -m solidworks_mcp.doc_links`, with tests under + `tests/solidworks_mcp/doc_links/` at 100% coverage. Network calls are + faked in the tests. +- New file `docs/llms.txt` (generated, committed). +- `.github/workflows/deploy-docs.yml`: the online check after deploy; a + weekly schedule. +- `dev-commands.ps1` and the Makefile: one command each for building + `llms.txt` and for the online check. +- Docs pages and the README: broken links fixed; a short contributor note + on regenerating `llms.txt`. +- Uses `httpx`, already a dependency. Does not touch COM or adapter code. diff --git a/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md b/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md new file mode 100644 index 00000000..f7d84b84 --- /dev/null +++ b/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md @@ -0,0 +1,53 @@ +## Purpose + +Every link in the README, the docs and `llms.txt` is checked: links within the project offline on every test run, and links to other sites online after each docs deploy and once a week. + +## ADDED Requirements + +### Requirement: Which links are checked + +The checks SHALL cover every link in `README.md`, every Markdown page under `docs/`, and `docs/llms.txt`: inline links, reference-style links, autolinks, and images. Links inside fenced or inline code SHALL be left out, since they are examples (such as `http://127.0.0.1:11434`), not links. `mailto:` links SHALL be left out. + +#### Scenario: An example URL in a code block +- **WHEN** a page shows `http://YOUR-WINDOWS-IP:8000` inside a code block +- **THEN** neither check visits it + +#### Scenario: A link in prose +- **WHEN** a page links to `https://modelcontextprotocol.io` in a sentence or a badge +- **THEN** the online check visits it + +### Requirement: Links within the project are checked offline + +On every test run, without network access, the check SHALL fail when a relative link (or a link to `site_url`) points at a page or file that does not exist, or at a `#anchor` that the target page has no heading or explicit `{#id}` for. Anchors SHALL be worked out the way the docs site makes them. + +#### Scenario: A moved page +- **WHEN** a page links to `getting-started/old-name.md` and that file does not exist +- **THEN** the check fails and names the page, the line and the link + +#### Scenario: A missing anchor +- **WHEN** a page links to `tools-overview.md#deprecated-tools` and that page has no heading whose anchor is `deprecated-tools` +- **THEN** the check fails and names the page, the line and the anchor + +#### Scenario: An anchor that exists +- **WHEN** a page links to `../progress.md` or to a heading or `{#ujoint}` id that exists +- **THEN** the check passes it + +### Requirement: Links to other sites are checked online + +A separate command SHALL visit every external URL once and fail when a URL does not answer with success, or when it redirects to a different site. A different site means a different host, with `www.` ignored; a link to this repository or the docs site that redirects anywhere outside them SHALL always fail. The command SHALL write a report listing every link, where it appears, the result and, for a redirect, where it went. Network trouble that is not the link's fault (a timeout) SHALL be retried before the link is failed. The command SHALL run after each docs deploy and once a week, and SHALL NOT run as part of the unit tests. + +#### Scenario: A dead link +- **WHEN** a URL answers 404, or its host does not resolve +- **THEN** the command fails and the report names the URL, every page and line it appears on, and the result + +#### Scenario: A redirect to another site +- **WHEN** a URL redirects to a different host (such as a lapsed domain parked elsewhere) +- **THEN** the command fails and the report shows the link and where it ended up, so the link can be updated or removed + +#### Scenario: A redirect on the same site +- **WHEN** `https://www.microsoft.com/windows` redirects to `https://www.microsoft.com/en-us/windows` +- **THEN** the link passes, and the report shows where it went + +#### Scenario: Every link is reported +- **WHEN** the command finishes +- **THEN** the report lists every external URL it visited, including the ones that passed, so a reader can see that every link was checked diff --git a/openspec/changes/own-llms-txt/specs/docs/llms-txt/spec.md b/openspec/changes/own-llms-txt/specs/docs/llms-txt/spec.md new file mode 100644 index 00000000..b528d60c --- /dev/null +++ b/openspec/changes/own-llms-txt/specs/docs/llms-txt/spec.md @@ -0,0 +1,53 @@ +## Purpose + +`llms.txt` tells agents what this project is and which pages to read. It is built from the project's own docs, so every word in it is a word the docs already say. + +## ADDED Requirements + +### Requirement: llms.txt is built from the docs nav + +The project SHALL publish an `llms.txt` at the docs site's root, built by a command from `mkdocs.yml` and the pages it lists, in the llms.txt format: an `# ` title line, a `> ` summary line, then one `## ` section per top-level nav section, each a list of `- [title](url): summary` entries. The title line SHALL be `site_name` and the summary line `site_description`. Pages SHALL appear in nav order. A nav entry that is not a Markdown page in `docs/` (such as the generated API reference) SHALL be left out. + +#### Scenario: Building the file +- **WHEN** the build command runs +- **THEN** it writes `docs/llms.txt` with one entry for every Markdown page in the nav, in nav order, under its nav section, and the site serves it at `/llms.txt` + +#### Scenario: A top-level page +- **WHEN** a page sits at the top level of the nav (such as Home or Demos) +- **THEN** it is listed under a `## Overview` section, which comes first + +#### Scenario: The committed file is stale +- **WHEN** a page's title or opening paragraph, or the nav, changes and `docs/llms.txt` is not rebuilt +- **THEN** the check fails, names the first line that differs, and says which command rebuilds the file + +### Requirement: Entries are copied word for word from their pages + +Each entry's title SHALL be the page's `# ` heading, and its summary the page's first paragraph of prose after that heading, both copied word for word. Prose means a paragraph that is not a blockquote, admonition, list, table, code block, image, badge line or HTML. Links inside the summary SHALL be reduced to their text; other Markdown (inline code, emphasis) SHALL be kept as written. A paragraph broken over several source lines SHALL be joined with single spaces. Nothing in the file SHALL be written by hand. + +#### Scenario: A page's opening paragraph +- **WHEN** a page's heading is `# Tools Overview` and its first prose paragraph is "The SolidWorks MCP Server provides 123 specialized tools for CAD automation. This page is a navigation map: …" +- **THEN** its entry is `- [Tools Overview](/user-guide/tools-overview/): The SolidWorks MCP Server provides 123 specialized tools …` with the paragraph in full + +#### Scenario: A page with no opening paragraph +- **WHEN** a nav page has no `# ` heading, or no prose paragraph before its first `## ` heading +- **THEN** the build fails and names the page, so the page gets a heading and an opening paragraph rather than the file getting hand-written text + +#### Scenario: An entry that doesn't match its page +- **WHEN** a line in `docs/llms.txt` is edited by hand so its title or summary differs from its page +- **THEN** the check fails and reports, for that line, the page, the expected text and the text found + +### Requirement: llms.txt holds only this project's own content + +Every URL in `llms.txt` SHALL be under the docs site (`site_url`) or this repository on GitHub (`repo_url`). The file SHALL contain no HTML tags, no HTML comments, and no invisible or direction-changing characters (zero-width characters, the byte-order mark, bidirectional controls, other format or control characters except the line break). Every line SHALL be one of the shapes the format allows (title, summary, section heading, entry, blank). + +#### Scenario: A third-party link +- **WHEN** a summary's source paragraph links to another site +- **THEN** the entry keeps only the link's text, and no URL outside this project appears in the file + +#### Scenario: Hidden text +- **WHEN** a page's title or opening paragraph contains a zero-width or bidirectional control character, or an HTML comment +- **THEN** the build fails and names the page and the character's code point + +#### Scenario: A line of the wrong shape +- **WHEN** `docs/llms.txt` contains a line that is not a title, summary, section heading, entry or blank line +- **THEN** the check fails and names the line diff --git a/openspec/changes/own-llms-txt/tasks.md b/openspec/changes/own-llms-txt/tasks.md new file mode 100644 index 00000000..0ed585d6 --- /dev/null +++ b/openspec/changes/own-llms-txt/tasks.md @@ -0,0 +1,40 @@ +## 1. Reading the docs + +- [ ] 1.1 `pyyaml` added to the `dev` and `test` extras; the `doc_links` package with `__init__.py` and its test package +- [ ] 1.2 `pages.py`: load `mkdocs.yml` with `!!python/...` tags ignored; walk `nav` into (section, nav title, path) in order, leaving out entries that aren't `.md` files in `docs/`; a page's URL from `site_url` with directory URLs; tests +- [ ] 1.3 A page's `# ` title and first prose paragraph (the skip rules in design decision 2; links reduced to their text; lines joined); a page with neither raises, naming it; tests for each skipped block kind +- [ ] 1.4 Heading ids: the toc slugify with `_1`, `_2` for repeats, plus `{#id}`; tests, and the parity test against `markdown.extensions.toc.slugify` over every docs heading (skipped without `markdown`) + +## 2. llms.txt + +- [ ] 2.1 `llms_txt.py` build: title and summary lines from `mkdocs.yml`, `## Overview` first, then the nav sections, entries in nav order; tests +- [ ] 2.2 The content rules shared by build and check: allowed URLs, line shapes, no `Cf`/`Cc` characters except `\n`, no HTML tag or comment; the builder names the page, the checker the line; tests for each rule +- [ ] 2.3 Check a committed text: stale (first differing line and the rebuild command); for an entry that differs, the page, the expected text and the text found; tests +- [ ] 2.4 `__main__.py` with `build`, `check`, `check-external`; exit codes; loguru output; tests + +## 3. Links + +- [ ] 3.1 `links.py` finder: inline, reference-style, autolinks and images, each with file and line; nothing inside fenced or inline code; `mailto:` skipped; tests +- [ ] 3.2 Offline check: relative links from the page (README from the repo root), `site_url` links mapped to `docs/`, non-Markdown files must exist, anchors against the target's heading ids; tests for a missing page, a missing anchor, a good anchor, an image +- [ ] 3.3 Online check (design decision 6): one GET per unique URL, the same-host rule, our-URL rule, retries, concurrency, User-Agent; faked transport in the tests for 200, 404, DNS failure, timeout then success, same-host and cross-host redirects +- [ ] 3.4 The Markdown report at `tests/.generated/link-report.md` listing every URL with its result and locations; tests + +## 4. Run it on the real docs + +- [ ] 4.1 Run the offline check on the README and docs; fix every broken link and anchor it finds, in the pages +- [ ] 4.2 Build `docs/llms.txt`; read every entry, and give each page whose opening reads badly (a "Last updated" line, a sentence ending in a colon, `docs/index.md`'s feedback note) a real opening paragraph, in the page; rebuild +- [ ] 4.3 Integration tests in `tests/integration/`: the committed `docs/llms.txt` matches a fresh build, and the offline check passes on the real docs +- [ ] 4.4 Run the online check by hand; fix or replace every dead or cross-site link it reports; record the counts in design decision 9 + +## 5. CI and commands + +- [ ] 5.1 `deploy-docs.yml`: a link-check job after `deploy`, and a weekly `schedule` that runs only that job; the report uploaded as an artifact +- [ ] 5.2 `dev-commands.ps1 dev-llms` / `dev-links` and `make llms` / `make links` +- [ ] 5.3 `mkdocs build --strict` copies `llms.txt` to the site root (checked in the built `site/`) + +## 6. Docs, review and sign-off + +- [ ] 6.1 CONTRIBUTING: a short note that `docs/llms.txt` is generated and how to rebuild it, and that page openings are its summaries; the CHANGELOG `Added` entries +- [ ] 6.2 Security review of the generated file (design decision 9): entry count, every URL ours, no hidden characters, no summary that reads as an instruction to an agent; recorded in the design +- [ ] 6.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`, `openspec validate --all` +- [ ] 6.4 Hand the user the file, the link report and the review (no live SolidWorks demo: nothing here touches SolidWorks); PR closing queue item 19, no attribution; archive and update the queue after the merge diff --git a/openspec/queue.md b/openspec/queue.md index 42d965ed..4e6a195b 100644 --- a/openspec/queue.md +++ b/openspec/queue.md @@ -21,7 +21,7 @@ Last updated 2026-11-14. | 8 | Experimental tools to stable: a live test for each of the 10, then promote it or record its fault | not filed yet | `experimental-tools-to-stable` (archived) | Done 2026-11-12 (2.0.0, tagged `v2.0.0`): all 10 promoted, signed off live. Pack and Go now copies the files `GetDependencies2` lists (SolidWorks 2026's own Pack and Go copied only the assembly); `comtypes` dropped | | 9 | Monitor stand demo follow-ups: feature order, `verify_model`'s planes, dimension listing, STL export, `create_sketch` on a face, the demo's camera | #206 | `monitor-stand-follow-ups` (archived) | Done 2026-11-14: all five live tests pass, GIF re-recorded; PR open | | 10 | An honest tool list: remove the 33 planned tools no item will build (the design table among them, after its live check), deprecate the stable duplicates for one release, settle a verb list. Replaces the old items "the 40 planned tools" and "duplicate tools" | #174 | `honest-tool-list` (archived) | Done 2026-11-14 (#229): 33 removed (the design table after its live check failed), 8 deprecated until 3.0.0, the verb list. Items 11-14 can start | -| 19 | Our own `llms.txt`, and every link checked. A script builds `llms.txt` from the mkdocs nav: each entry's title and summary are copied word for word from the page they link to, and nothing is written by hand. A check follows EVERY link in `llms.txt`, the README and the docs (internal pages, anchors and external URLs), and fails on a dead link, a redirect off this repo, or an `llms.txt` line that doesn't match its page. Security review of the result: only this repo's own pages, no third-party links, no hidden text or instructions. PR #225's file is not used as a starting point; the user is closing that PR | #225 (closed, not merged) | not yet written | Added 2026-11-14 at the user's request. Next after item 10, so the file lists only working tools | +| 19 | Our own `llms.txt`, and every link checked. A script builds `llms.txt` from the mkdocs nav: each entry's title and summary are copied word for word from the page they link to, and nothing is written by hand. A check follows EVERY link in `llms.txt`, the README and the docs (internal pages, anchors and external URLs), and fails on a dead link, a redirect off this repo, or an `llms.txt` line that doesn't match its page. Security review of the result: only this repo's own pages, no third-party links, no hidden text or instructions. PR #225's file is not used as a starting point; the user is closing that PR | #225 (closed, not merged) | `own-llms-txt` | Added 2026-11-14 at the user's request. Planned 2026-11-14. Next after item 10, so the file lists only working tools | | 11 | Part features the peers lead with: Hole Wizard holes, cosmetic threads, a linear feature pattern, shell, draft, rib, and sketch convert-entities | #105 | `part-feature-depth` | Planned 2026-11-12 | | 12 | The drawing pack, where no peer goes: section and detail views, the title block and sheet format, drawing dimensions, and one drawing check | #102, #158 | `drawing-pack` | Planned 2026-11-12. Builds the 7 planned drawing tools item 10 leaves | | 13 | Configurations: create, activate and delete one, and suppress a feature or set a dimension in one configuration only | none | `configuration-tools` | Planned 2026-11-12 | From c9a6e81369bb5bb198f6f0ae506591c817148d40 Mon Sep 17 00:00:00 2001 From: Andrew Bartels Date: Sun, 15 Nov 2026 19:43:12 -0800 Subject: [PATCH 3/4] feat(docs): our own llms.txt, built word for word from the docs, and every link checked docs/llms.txt is generated from the mkdocs nav: each entry's title and summary are the page's heading and opening paragraph, copied word for word. A test fails when the file and the pages disagree, when it links outside this project, or when it holds HTML or hidden characters. Links within the project (pages, files, anchors, repository files) are checked on every test run; every link to another site after each docs deploy and weekly, with a report of every URL. Ten pages got a real opening paragraph; one moved link was updated. Queue item 19. --- .github/workflows/deploy-docs.yml | 42 ++ CHANGELOG.md | 12 + CONTRIBUTING.md | 10 + Makefile | 9 +- dev-commands.ps1 | 15 +- docs/agents/agent-skill.md | 3 +- docs/agents/agents-and-testing.md | 2 +- docs/agents/com-api-pitfalls.md | 6 +- docs/agents/sample-models-guide.md | 4 +- docs/agents/worked-examples.md | 4 +- docs/getting-started/local-llm.md | 4 +- docs/getting-started/solidworks-as-code.md | 4 +- .../tutorial-parts/u_joint_rebuild_prompt.md | 2 +- docs/getting-started/vscode-mcp-setup.md | 2 + docs/index.md | 2 +- docs/llms.txt | 75 +++ docs/planning/roadmap.md | 6 +- docs/planning/solidworks-api-coverage.md | 2 + docs/user-guide/integration-testing.md | 4 +- docs/user-guide/solidworks-ui-llm-tutorial.md | 2 +- openspec/changes/own-llms-txt/design.md | 60 ++- .../specs/docs/link-check/spec.md | 12 +- openspec/changes/own-llms-txt/tasks.md | 44 +- pyproject.toml | 2 + src/solidworks_mcp/doc_links/__init__.py | 12 + src/solidworks_mcp/doc_links/__main__.py | 91 ++++ src/solidworks_mcp/doc_links/links.py | 502 ++++++++++++++++++ src/solidworks_mcp/doc_links/llms_txt.py | 243 +++++++++ src/solidworks_mcp/doc_links/pages.py | 391 ++++++++++++++ tests/integration/test_llms_txt_up_to_date.py | 28 + tests/solidworks_mcp/doc_links/__init__.py | 0 tests/solidworks_mcp/doc_links/conftest.py | 55 ++ .../solidworks_mcp/doc_links/test___main__.py | 88 +++ tests/solidworks_mcp/doc_links/test_links.py | 384 ++++++++++++++ .../solidworks_mcp/doc_links/test_llms_txt.py | 167 ++++++ tests/solidworks_mcp/doc_links/test_pages.py | 155 ++++++ 36 files changed, 2395 insertions(+), 49 deletions(-) create mode 100644 docs/llms.txt create mode 100644 src/solidworks_mcp/doc_links/__init__.py create mode 100644 src/solidworks_mcp/doc_links/__main__.py create mode 100644 src/solidworks_mcp/doc_links/links.py create mode 100644 src/solidworks_mcp/doc_links/llms_txt.py create mode 100644 src/solidworks_mcp/doc_links/pages.py create mode 100644 tests/integration/test_llms_txt_up_to_date.py create mode 100644 tests/solidworks_mcp/doc_links/__init__.py create mode 100644 tests/solidworks_mcp/doc_links/conftest.py create mode 100644 tests/solidworks_mcp/doc_links/test___main__.py create mode 100644 tests/solidworks_mcp/doc_links/test_links.py create mode 100644 tests/solidworks_mcp/doc_links/test_llms_txt.py create mode 100644 tests/solidworks_mcp/doc_links/test_pages.py diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 1857170f..a16922c4 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -7,6 +7,10 @@ on: pull_request: branches: - main + schedule: + # Weekly: check every link in the docs (the link-check job only). + - cron: '0 6 * * 1' + workflow_dispatch: permissions: contents: read @@ -23,6 +27,7 @@ concurrency: jobs: test: + if: github.event_name != 'schedule' runs-on: ubuntu-latest steps: - name: Checkout @@ -108,3 +113,40 @@ jobs: id: deployment uses: actions/deploy-pages@v5 + # Every link in the README, the docs and llms.txt, after each deploy and + # weekly (spec docs/link-check). A failure flags a link to fix; it does not + # undo the deploy. + link-check: + if: >- + always() && (github.event_name == 'schedule' || + github.event_name == 'workflow_dispatch' || + needs.deploy.result == 'success') + runs-on: ubuntu-latest + needs: deploy + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@v7 + + - name: Setup Python + uses: actions/setup-python@v7 + with: + python-version: '3.13' + + - name: Install package + run: | + python -m pip install --upgrade pip + pip install -e . "pyyaml>=6.0" + + - name: Check every link + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: python -m solidworks_mcp.doc_links check-external + + - name: Upload the link report + if: always() + uses: actions/upload-artifact@v7 + with: + name: link-report + path: tests/.generated/link-report.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 3925fe14..8ed45b7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- **Our own `llms.txt`**, served at the docs site's root and built from the + docs: each entry's title and summary are copied word for word from its + page, and a test fails when the file and the pages disagree, when it + links outside this project, or when it holds HTML or hidden characters. + Nothing in it is written by hand. Ten pages got a real opening paragraph + to serve as their summary. +- **Every link in the docs is checked.** Links within the project (pages, + files, anchors, repository files) on every test run; every link to + another site after each docs deploy and weekly, failing a dead link or a + redirect to a different site, with a report of every URL + (`python -m solidworks_mcp.doc_links check-external`). The first run + fixed one moved link (the Anthropic console). - **`create_sketch` takes `face_point`** (#206): a point in mm on a flat face of the body, in place of `plane`. The sketch opens on that face and moves with it when the model changes, so a pocket cut from it follows a diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d01e2cdf..ae2a5d49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,6 +89,16 @@ When needed (credentials/SolidWorks environment available): - Update docs for user-visible behavior changes. - Keep architecture docs implementation-accurate. - Put roadmap/aspirational content in `docs/planning/`, not runtime architecture pages. +- Every page in the nav opens with a `# ` title and a plain paragraph that + says what the page is. `docs/llms.txt` is built from those: each entry's + title and summary are copied word for word from its page, so never edit + the file by hand. After changing a page's title or opening, or the nav, + run `.\dev-commands.ps1 dev-llms` (or + `python -m solidworks_mcp.doc_links build`) and commit the result; a test + fails until you do. The same test checks every relative link and anchor. +- `.\dev-commands.ps1 dev-links` visits every external link and writes + `tests/.generated/link-report.md`. CI runs it after each docs deploy and + weekly. Current docs structure: diff --git a/Makefile b/Makefile index c258e30c..72606b0a 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # SolidWorks MCP Server - Simplified Makefile -.PHONY: help install test test-context-budget test-full test-clean docs build run clean lint format +.PHONY: help install test test-context-budget llms links test-full test-clean docs build run clean lint format # Default target .DEFAULT_GOAL := help @@ -57,6 +57,13 @@ test: ## Run test suite with coverage --durations=10 \ -v +llms: ## Rebuild docs/llms.txt, then check it and every project link (offline) + python -m solidworks_mcp.doc_links build + python -m solidworks_mcp.doc_links check + +links: ## Visit every external link in the docs (online) + python -m solidworks_mcp.doc_links check-external + test-context-budget: ## Run smoke response-size guard test (CI-friendly) @echo "$(BLUE)Running smoke response-size guard test...$(NC)" @if [ -z "$(CONDA_CMD)" ]; then \ diff --git a/dev-commands.ps1 b/dev-commands.ps1 index e9843774..a789c512 100644 --- a/dev-commands.ps1 +++ b/dev-commands.ps1 @@ -132,6 +132,8 @@ function dev-help { Write-Host " dev-ui Start the FastAPI UI backend" Write-Host " dev-docs-build Build documentation once (mkdocs build --clean)" Write-Host " dev-docs-strict Build documentation in strict mode" + Write-Host " dev-llms Rebuild docs/llms.txt from the docs, then check it and every project link" + Write-Host " dev-links Visit every external link in the docs (online; writes tests/.generated/link-report.md)" Write-Host " dev-docs-audit Run verbose + strict docs audit and write summary" Write-Host " dev-docs Build and serve documentation (http://localhost:8000)" Write-Host " dev-docs-discovery Index SolidWorks COM/VBA documentation (Windows + SW running)" @@ -385,7 +387,8 @@ function dev-ui { # FastAPI backend (solidworks_mcp.ui.server:app) - still real, # independent infrastructure other things build on. Write-Host "Starting UI backend (FastAPI)..." -ForegroundColor Cyan - & (Join-Path $PSScriptRoot "scripts un-ui.ps1") + & (Join-Path $PSScriptRoot "scripts +un-ui.ps1") } function dev-docs { @@ -403,6 +406,16 @@ function dev-docs-build { else { Write-Host "Docs build failed." -ForegroundColor Red } } +function dev-llms { + $py = Get-VenvPython + & $py -m solidworks_mcp.doc_links build + if ($LASTEXITCODE -eq 0) { & $py -m solidworks_mcp.doc_links check } +} + +function dev-links { + & (Get-VenvPython) -m solidworks_mcp.doc_links check-external +} + function dev-docs-strict { Write-Host "Building docs in strict mode..." -ForegroundColor Cyan & (Join-Path $PSScriptRoot "scripts\docs\build-docs.ps1") -Strict diff --git a/docs/agents/agent-skill.md b/docs/agents/agent-skill.md index cd0dcd4a..fe209514 100644 --- a/docs/agents/agent-skill.md +++ b/docs/agents/agent-skill.md @@ -1,6 +1,7 @@ # Agent Skill -The server ships a skill, `solidworks-mcp`, for agents that use its tools. +The server ships a skill, `solidworks-mcp`, that teaches agents how to use its tools together: the order to build in, units, choosing geometry, checking results and recovering from errors. + Each tool's own description says what that tool does ([Tool Description Standard](tool-description-standard.md)); the skill covers what spans tools: diff --git a/docs/agents/agents-and-testing.md b/docs/agents/agents-and-testing.md index e32e47dc..97e7da54 100644 --- a/docs/agents/agents-and-testing.md +++ b/docs/agents/agents-and-testing.md @@ -245,7 +245,7 @@ You should see structured JSON output like this: === "Anthropic API (BYOK)" Requires an Anthropic account with active billing credits (separate from Claude Code subscription). - Get your key at: https://console.anthropic.com/settings/keys + Get your key at: https://platform.claude.com/settings/keys ```powershell [System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User") diff --git a/docs/agents/com-api-pitfalls.md b/docs/agents/com-api-pitfalls.md index 0d894b84..2fac6e54 100644 --- a/docs/agents/com-api-pitfalls.md +++ b/docs/agents/com-api-pitfalls.md @@ -1,9 +1,11 @@ # COM API Pitfalls for LLM Agents -This page documents hard-won lessons from debugging the SolidWorks COM bridge. +This page documents hard-won lessons from debugging the SolidWorks COM bridge, +for anyone changing the server's COM code. Every entry below caused a real +runtime failure that required hours to diagnose. + If you are an AI coding assistant (Claude, GPT-4, Gemini, Copilot, etc.) working on this codebase, **read this page before touching any COM-related code**. -Every entry below caused a real runtime failure that required hours to diagnose. !!! tip "For LLM agents" The patterns here are not obvious from the SolidWorks API docs alone. diff --git a/docs/agents/sample-models-guide.md b/docs/agents/sample-models-guide.md index aecb4f14..53b78c95 100644 --- a/docs/agents/sample-models-guide.md +++ b/docs/agents/sample-models-guide.md @@ -1,6 +1,8 @@ # Sample Models Guide -This guide describes the SolidWorks 2026 learn samples shipped with SolidWorks and explains which MCP tools and prompting strategies best recreate each part from scratch. Reference files live at: +This guide describes the SolidWorks 2026 learn samples shipped with SolidWorks and explains which MCP tools and prompting strategies best recreate each part from scratch. + +Reference files live at: ``` C:\Users\Public\Documents\SOLIDWORKS\SOLIDWORKS 2026\samples\learn\ diff --git a/docs/agents/worked-examples.md b/docs/agents/worked-examples.md index cea9034a..e520a477 100644 --- a/docs/agents/worked-examples.md +++ b/docs/agents/worked-examples.md @@ -1,6 +1,8 @@ # Worked Examples: SolidWorks MCP + Agent Workflow -This page shows three practical reconstruction examples using the same inspect -> classify -> delegate loop: +This page shows three practical reconstruction examples, each using the same inspect, classify and delegate loop. + +The loop: 1. Read the original model state. 2. Classify the feature family before writing geometry. diff --git a/docs/getting-started/local-llm.md b/docs/getting-started/local-llm.md index 07f4214e..da86ba91 100644 --- a/docs/getting-started/local-llm.md +++ b/docs/getting-started/local-llm.md @@ -1,6 +1,8 @@ # Local LLM with Ollama (Gemma 4) -The SolidWorks MCP UI can route all LLM calls to a local Ollama instance instead of GitHub Models or OpenAI. This works offline, keeps design data private, and uses Ollama's OpenAI-compatible endpoint at `http://127.0.0.1:11434/v1`. +The SolidWorks MCP UI can route all LLM calls to a local Ollama instance instead of GitHub Models or OpenAI. This works offline and keeps design data private. + +It uses Ollama's OpenAI-compatible endpoint at `http://127.0.0.1:11434/v1`. The official Ollama Gemma 4 library page is here: diff --git a/docs/getting-started/solidworks-as-code.md b/docs/getting-started/solidworks-as-code.md index b330168a..27cad38c 100644 --- a/docs/getting-started/solidworks-as-code.md +++ b/docs/getting-started/solidworks-as-code.md @@ -1,6 +1,8 @@ # SolidWorks as Code (SoC) -SolidWorks as Code lets you record an interactive MCP session and export it as a clean, runnable Python script. The round-trip is: +SolidWorks as Code lets you record an interactive MCP session and export it as a clean, runnable Python script. + +The round-trip is: ```text MCP tool calls → SQLite log → soc_exporter → script.py diff --git a/docs/getting-started/tutorial-parts/u_joint_rebuild_prompt.md b/docs/getting-started/tutorial-parts/u_joint_rebuild_prompt.md index d1ab3445..4598d134 100644 --- a/docs/getting-started/tutorial-parts/u_joint_rebuild_prompt.md +++ b/docs/getting-started/tutorial-parts/u_joint_rebuild_prompt.md @@ -1,6 +1,6 @@ # U-Joint Rebuild Prompts -**Note:** These prompts are for when you have access to the reference SolidWorks sample models and want to match them exactly. For learning and from-scratch builds, start with the [U-Joint Assembly Tutorial](../tutorials/u-joint-assembly-build.md) instead. +These prompts rebuild the U-Joint from SolidWorks' sample models, for when you have the reference models and want to match them exactly. For learning and from-scratch builds, start with the [U-Joint Assembly Tutorial](../tutorials/u-joint-assembly-build.md) instead. Reference models location: diff --git a/docs/getting-started/vscode-mcp-setup.md b/docs/getting-started/vscode-mcp-setup.md index ab2bbd49..2b853464 100644 --- a/docs/getting-started/vscode-mcp-setup.md +++ b/docs/getting-started/vscode-mcp-setup.md @@ -1,5 +1,7 @@ # VS Code MCP Setup +Connect VS Code's MCP client to the SolidWorks MCP server, with the setup command or by editing `mcp.json` by hand. + ## Connect with setup With [uv](https://docs.astral.sh/uv/) installed: diff --git a/docs/index.md b/docs/index.md index cd31cb1f..5780e92d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ [![Tests](https://github.com/andrewbartels1/SolidworksMCP-python/actions/workflows/ci.yml/badge.svg)](https://github.com/andrewbartels1/SolidworksMCP-python/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/andrewbartels1/SolidworksMCP-python/branch/main/graph/badge.svg)](https://codecov.io/gh/andrewbartels1/SolidworksMCP-python) -**AI-Assisted SolidWorks Automation with MCP** +An MCP server that lets AI agents drive SolidWorks: describe a part, and the agent builds it with the server's 123 tools and checks what SolidWorks reports back. 🚀 **123 Tools** | 🤖 **Agent-Ready Workflows** | ⚡ **Automatic COM/VBA Routing** | 🧪 **Schema-Validated Prompt Runs** diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 00000000..4ce05677 --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,75 @@ +# SolidWorks MCP Server + +> Python MCP server for SolidWorks automation with 123 tools + +## Overview + +- [SolidWorks MCP Server](https://andrewbartels1.github.io/SolidworksMCP-python/): An MCP server that lets AI agents drive SolidWorks: describe a part, and the agent builds it with the server's 123 tools and checks what SolidWorks reports back. +- [Demos](https://andrewbartels1.github.io/SolidworksMCP-python/demos/): Every demo on this page drove a real SolidWorks 2026 session through the same MCP tools an MCP client calls, and checked what SolidWorks reported back. Each GIF was captured from that run, with the tool call and its result captioned beneath the SolidWorks window. +- [Progress](https://andrewbartels1.github.io/SolidworksMCP-python/progress/): How far to trust each tool, and how much of SolidWorks' COM API the project reaches. Everything on this page is generated from the code by `python -m solidworks_mcp.progress.generate`, and a test fails when it's out of date, so it moves with every tool added or fixed. +- [Compatibility](https://andrewbartels1.github.io/SolidworksMCP-python/compatibility/): The SolidWorks releases the selftest has been run on, and how each area did. The server is developed against SolidWorks 2026; every other row comes from a user's report. + +## Getting Started + +- [Installation Guide](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/installation/): Real SolidWorks automation needs Windows 10 or 11 with SolidWorks installed and opened at least once. Linux and WSL work for the docs, the tests and mock mode. +- [Quick Start Guide](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/quickstart/): Get running quickly with the verified Windows setup. +- [Tutorial Tracks](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/tutorial-tracks/): Build SolidWorks parts from scratch using the MCP server and Python scripting. +- [SolidWorks as Code (SoC)](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/solidworks-as-code/): SolidWorks as Code lets you record an interactive MCP session and export it as a clean, runnable Python script. +- [Getting Started: Building SolidWorks Parts with Python](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/tutorials/u-joint-assembly-build/): This tutorial takes you from zero to three completed SolidWorks parts — no prior Python or CAD automation experience required. By the end you will understand how the MCP adapter talks to SolidWorks, how to run and read build scripts, how to interpret errors, and how the checkpoint-and-restore workflow lets you recover from mistakes without undoing 20 mouse clicks. +- [U-Joint Rebuild Prompts](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/tutorial-parts/u_joint_rebuild_prompt/): These prompts rebuild the U-Joint from SolidWorks' sample models, for when you have the reference models and want to match them exactly. For learning and from-scratch builds, start with the U-Joint Assembly Tutorial instead. +- [Heat-Insert Coupon Recording Prompt](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/tutorial-parts/heat_insert_recording_prompt/): The prompt below reproduces `demo_recording_heat_insert.py` — a recording-friendly script that pauses between every build step so each feature is visible on screen, for screen-recording an MCP-driven modeling session end to end. +- [Prompt-Driven Walkthrough: Smart Dimensions, Reference Points, Save Bodies & Center Marks](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/tutorials/wave3-reference-geometry-and-drawings/): This tutorial reproduces a live session that was run end-to-end against **SolidWorks 3DEXPERIENCE R2026x** through the MCP server. Every screenshot on this page was captured with the `export_image` tool during that run — nothing is mocked. +- [VS Code MCP Setup](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/vscode-mcp-setup/): Connect VS Code's MCP client to the SolidWorks MCP server, with the setup command or by editing `mcp.json` by hand. +- [Claude Code MCP Setup](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/claude-code-setup/): This guide shows complete beginners how to connect Claude Code to the SolidWorks MCP server. +- [Local LLM with Ollama (Gemma 4)](https://andrewbartels1.github.io/SolidworksMCP-python/getting-started/local-llm/): The SolidWorks MCP UI can route all LLM calls to a local Ollama instance instead of GitHub Models or OpenAI. This works offline and keeps design data private. + +## MCP Server Guide + +- [Architecture Overview](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/architecture/): The SolidWorks MCP Server implements an intelligent, multi-layered architecture designed to overcome the limitations of traditional COM-based SolidWorks automation while providing enterprise-grade reliability and security. +- [Tools Overview](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tools-overview/): The SolidWorks MCP Server provides 123 specialized tools for CAD automation. This page is a navigation map: each card links to the family's catalog page, which lists every tool with its inputs and a sample call. +- [Platform and Connectivity](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/platform-connectivity/): This guide explains how to run SolidWorks MCP when your day-to-day workflow is Linux/WSL but real SolidWorks automation must run on Windows. +- [Prompting Best Practices for SolidWorks MCP](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/prompting-best-practices/): This guide is designed for mechanical engineers and CAD users who are new to MCP tool calling. +- [Integration Testing (Real SolidWorks)](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/integration-testing/): This project has two test modes: a fast default mode that needs no SolidWorks, and a full mode that adds real SolidWorks integration tests. +- [Real SolidWorks Tool Validation Matrix](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/real-tool-validation-matrix/): This page documents what is validated with real SolidWorks and what is still simulated. +- [SolidWorks UI + LLM Tutorial](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/solidworks-ui-llm-tutorial/): This tutorial is for mechanical engineers who are new to MCP tools and want a repeatable way to drive SolidWorks from an LLM while still using the SolidWorks UI. This is meant to help take the repetition out of a workflow and optimize an engineer's time on the design and things that matter, not dull repetitive tasks. +- [Screenshot Equivalence Workflow](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/screenshot-equivalence/): This page describes how to validate that an LLM-generated SolidWorks model is geometrically equivalent to a reference model using automated screenshot comparison. + +## Tool Catalog + +- [Tool Catalog — All 123 Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/): This reference documents all **123 MCP tools** registered by the SolidWorks MCP server. Each section covers one functional category with parameter tables and copy-paste sample calls. +- [Modeling Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/modeling/): Create and manipulate SolidWorks parts, assemblies, and drawings. These are the foundational tools for any CAD workflow — opening files, creating features (extrude, revolve), and querying/setting driven dimensions. +- [Sketching Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/sketching/): Build 2-D sketch geometry (lines, circles, arcs, splines, polygons) and apply geometric constraints and driven dimensions. Sketches are the prerequisite for every extrusion, revolve, sweep, and loft feature. +- [Drawing Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/drawing/): Create and edit 2-D technical drawings: views, notes and centre marks. Section and detail views, drawing dimensions, the title block, the sheet format and a drawing check are planned in the drawing pack; until then they return `not_supported`. +- [Drawing Analysis Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/drawing-analysis/): Compare two versions of a drawing file on disk. A check of a drawing's contents (`check_drawing`) is planned in the drawing pack. +- [Drawing Automation Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/drawing-automation/): Put the model's dimensions on a drawing and lay them out so nothing overlaps, add a bill of materials, set the sheet scale, or make a complete A3 drawing of a part or assembly in one call. +- [Engineering Data Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/engineering-data/): Read and edit the data drawings, BOMs and analyses are built from: every model dimension by name, measurements between faces, edges and vertices, materials, custom properties, and sheet-metal flat patterns. +- [Analysis Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/analysis/): Use these after a model or assembly already exists. To check a finished build in one call, use `verify_model`. For individual readings, use `get_mass_properties` and `check_interference`. +- [Export Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/export/): Convert SolidWorks models to industry-standard interchange and manufacturing formats: STEP, IGES, STL, PDF, DWG, and raster images. To export many files, call the export tool once per file. +- [File Management Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/file-management/): Open, save, switch and inspect SolidWorks documents: `open_model`, `save_file` and `save_as`, the open documents, the feature tree, configurations, the current selection and Pack and Go. `load_part`, `load_assembly`, `save_part`, `save_assembly` and `get_file_properties` are deprecated; each section names its replacement. +- [Automation Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/automation/): `generate_vba_code` writes a VBA macro skeleton for a step the other tools don't cover. For variants of a part, use configurations (planned in queue item 13). +- [VBA Generation Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/vba-generation/): Generate and execute VBA macro code for operations that exceed the COM direct-call parameter limit (typically > 12 params). Covers extrusions, revolves, assembly inserts, mates, drawing views, batch exports, file operations, and macro recording scaffolding. +- [Template Management Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/template-management/): Compare two SolidWorks template files (.prtdot, .asmdot, .drwdot) on disk. To start a part from a template, give `template` to `create_part`. +- [Macro Recording Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/macro-recording/): Run a binary SolidWorks macro (`.swp`). Record macros in SolidWorks itself (Tools > Macro > Record); to write one from a description, use `generate_vba_code`. +- [Docs Discovery Tools](https://andrewbartels1.github.io/SolidworksMCP-python/user-guide/tool-catalog/docs-discovery/): Look up SolidWorks API interfaces, methods and properties, with each member's parameters, return type and description. Everything is read from the SolidWorks type library installed on this machine, so the answers match your SolidWorks version and nothing is hand-typed. + +## Agents and Skills + +- [Agents and Prompt Testing](https://andrewbartels1.github.io/SolidworksMCP-python/agents/agents-and-testing/): This guide is written for people who know SolidWorks well but are new to LLM agents and AI-assisted workflows. +- [Family-Gated Tool Routing for Interactive CAD Reconstruction](https://andrewbartels1.github.io/SolidworksMCP-python/agents/family-gated-tool-routing/): This page defines how the orchestration agent should shortlist tools by feature family, so the LLM does not reason over the full tool surface at every step. +- [PydanticAI and Pydantic in This Project](https://andrewbartels1.github.io/SolidworksMCP-python/agents/pydantic-ai-and-schemas/): This section explains where schema-driven validation belongs and how it relates to the MCP server. +- [Agent Memory and Recovery (SQLite MVP)](https://andrewbartels1.github.io/SolidworksMCP-python/agents/agent-memory-and-recovery/): This documents a simple local SQLite strategy to help agents avoid repeated failures and recover from broken design states. +- [Agent UI Workflows (Planning)](https://andrewbartels1.github.io/SolidworksMCP-python/agents/agent-ui-workflows/): This page outlines practical UI options for visually guiding users through agent decisions like hinge selection, sourcing, and printability checks. +- [Logging Configuration and Agent Invocation Guide](https://andrewbartels1.github.io/SolidworksMCP-python/agents/logging-and-agent-invocation/): This guide explains how to enable, configure, and use the logging infrastructure for SolidWorks MCP tool execution and multi-turn conversational design workflows. +- [From Screenshot to SolidWorks: The Image-First Reconstruction Workflow](https://andrewbartels1.github.io/SolidworksMCP-python/agents/reverse-engineering-workflow/): This tutorial shows how to take a screenshot or rendered image of a part — including the sample parts that ship with SolidWorks — and use prompting to recreate it from scratch using the MCP server. +- [Sample Models Guide](https://andrewbartels1.github.io/SolidworksMCP-python/agents/sample-models-guide/): This guide describes the SolidWorks 2026 learn samples shipped with SolidWorks and explains which MCP tools and prompting strategies best recreate each part from scratch. +- [Worked Examples: SolidWorks MCP + Agent Workflow](https://andrewbartels1.github.io/SolidworksMCP-python/agents/worked-examples/): This page shows three practical reconstruction examples, each using the same inspect, classify and delegate loop. +- [Prompt-Driven Design with SolidWorks MCP](https://andrewbartels1.github.io/SolidworksMCP-python/agents/prompt-driven-design/): You know SolidWorks. This guide shows you how to describe what you want to build in plain language, let an LLM translate that into the right tool calls, and have SolidWorks build it — without clicking through menus. +- [Tool Description Standard](https://andrewbartels1.github.io/SolidworksMCP-python/agents/tool-description-standard/): An agent picks a tool from its description and input schema alone, before it has called anything. This page is the standard every MCP tool in this server follows, so that what an agent reads is enough to choose the right tool, call it correctly, and know what happened. +- [Agent Skill](https://andrewbartels1.github.io/SolidworksMCP-python/agents/agent-skill/): The server ships a skill, `solidworks-mcp`, that teaches agents how to use its tools together: the order to build in, units, choosing geometry, checking results and recovering from errors. +- [Prompting Tutorials](https://andrewbartels1.github.io/SolidworksMCP-python/agents/prompting-tutorials/): This page documents the **best-performing LLM prompts** for creating SolidWorks parts via the MCP server. Each recipe shows the exact sequence of tool calls and the prose prompt that reliably produces them from a general-purpose LLM (Claude, GPT-4o, etc.). +- [COM API Pitfalls for LLM Agents](https://andrewbartels1.github.io/SolidworksMCP-python/agents/com-api-pitfalls/): This page documents hard-won lessons from debugging the SolidWorks COM bridge, for anyone changing the server's COM code. Every entry below caused a real runtime failure that required hours to diagnose. + +## Planning + +- [Roadmap](https://andrewbartels1.github.io/SolidworksMCP-python/planning/roadmap/): This page tracks the order the open backlog gets worked in. +- [SolidWorks API Coverage Map](https://andrewbartels1.github.io/SolidworksMCP-python/planning/solidworks-api-coverage/): This page maps every major SolidWorks API area against what this MCP server implements, as a planning reference for new tools. diff --git a/docs/planning/roadmap.md b/docs/planning/roadmap.md index 2c62568b..1cf47a3c 100644 --- a/docs/planning/roadmap.md +++ b/docs/planning/roadmap.md @@ -1,8 +1,8 @@ # Roadmap -**Last updated:** 2026-10-31 +This page tracks the order the open backlog gets worked in. -This page tracks the order the open backlog gets worked in. It replaces the +It replaces the old `docs/planning/ROADMAP_2026_2027.md`, which described a GUI-dashboard-first, PydanticAI-agent-first strategy that was superseded on 2026-05-17 when the project pivoted to [SolidWorks-as-Code](../getting-started/solidworks-as-code.md) @@ -15,6 +15,8 @@ For per-tool SolidWorks COM API coverage (what's implemented vs. missing at the interface/method level), see [SolidWorks API Coverage](solidworks-api-coverage.md). +**Last updated:** 2026-10-31 + ## How work is ordered Open issues are ranked in four tiers, then by order within each tier: diff --git a/docs/planning/solidworks-api-coverage.md b/docs/planning/solidworks-api-coverage.md index 2dd08e4b..cb34c2af 100644 --- a/docs/planning/solidworks-api-coverage.md +++ b/docs/planning/solidworks-api-coverage.md @@ -1,5 +1,7 @@ # SolidWorks API Coverage Map +This page maps every major SolidWorks API area against what this MCP server implements, as a planning reference for new tools. + **Last updated:** 2026-06-13 **Reference:** SolidWorks 2026 API (SOLIDWORKS COM API via pywin32) **Purpose:** Planning reference for future tool development — maps every major SolidWorks API functional category against what this MCP server currently implements. diff --git a/docs/user-guide/integration-testing.md b/docs/user-guide/integration-testing.md index 1d433787..515079ca 100644 --- a/docs/user-guide/integration-testing.md +++ b/docs/user-guide/integration-testing.md @@ -1,6 +1,8 @@ # Integration Testing (Real SolidWorks) -This project now includes two test modes: +This project has two test modes: a fast default mode that needs no SolidWorks, and a full mode that adds real SolidWorks integration tests. + +The two modes: - Default mode: fast tests, mock-friendly, no real SolidWorks dependency. - Full mode: includes real SolidWorks integration tests. diff --git a/docs/user-guide/solidworks-ui-llm-tutorial.md b/docs/user-guide/solidworks-ui-llm-tutorial.md index cdf2194f..36de529d 100644 --- a/docs/user-guide/solidworks-ui-llm-tutorial.md +++ b/docs/user-guide/solidworks-ui-llm-tutorial.md @@ -1,6 +1,6 @@ # SolidWorks UI + LLM Tutorial -This tutorial is for mechanical engineers who are new to MCP tools and want a repeatable way to drive SolidWorks from an LLM while still using the SolidWorks UI. This is meant to help take the repetition out of a workflow and optimize and engineer's time on the design and things that matter, not dull repetitive tasks. +This tutorial is for mechanical engineers who are new to MCP tools and want a repeatable way to drive SolidWorks from an LLM while still using the SolidWorks UI. This is meant to help take the repetition out of a workflow and optimize an engineer's time on the design and things that matter, not dull repetitive tasks. ## What This Tutorial Covers diff --git a/openspec/changes/own-llms-txt/design.md b/openspec/changes/own-llms-txt/design.md index 758a5b2b..262e6f7b 100644 --- a/openspec/changes/own-llms-txt/design.md +++ b/openspec/changes/own-llms-txt/design.md @@ -133,9 +133,13 @@ when `markdown` isn't installed. - One `GET` per unique URL (some sites refuse `HEAD`), following redirects, 15 s timeout, a plain `User-Agent` naming the project (no personal details), up to 8 at a time. -- Pass: final status 2xx, and the final host equals the original with a - leading `www.` ignored. A URL under `repo_url` or `site_url` must end - under one of them. +- Pass: final status 2xx, and the redirects stayed on the same site: the + same host (`www.` ignored), a subdomain either way, or a host listed in + `SAME_SITE` with a reason. (Changed after the first run, below.) +- GitHub issue and pull request links are checked through + `api.github.com/repos///issues/`, with the CI token when + one is set; the pages answer 429 to scripts. At most two requests at + once per host. - Retry twice on timeouts, connection resets and 429/5xx, with a short back-off; a 4xx other than 429, or a host that doesn't resolve, fails at once. @@ -163,12 +167,50 @@ The package imports `yaml` at module level. `pyyaml` is added to the mkdocs). The server never imports `doc_links`, so no runtime dependency is added. -### 9. Security review, recorded at the end - -Task 6 reads the generated file line by line and records here: the -count of entries, that every URL is ours (the check proves it, the -review confirms it), that no summary reads as an instruction to an -agent, and the result of the first online run. +### 9. Security review and the first runs (2026-11-15) + +**The file.** 54 entries in six sections (Overview 4, Getting Started 11, +MCP Server Guide 8, Tool Catalog 15, Agents and Skills 14, Planning 2). +Every URL is under `site_url`; the checker proves it on every test run. +No HTML, no comments, no control or format characters. Every line was +read by hand: + +- Ten pages opened badly and were fixed in the page: the home page (a + bold tagline), the VS Code setup (no opening at all), the U-Joint + prompts (a "**Note:**"), integration testing, worked examples, SoC and + the sample models guide (sentences ending in a colon), the agent skill, + the roadmap and the API coverage map ("Last updated" lines first). +- The local-LLM page's opening carried `http://127.0.0.1:11434/v1`; the + address moved to the page's second paragraph, so the strict URL rule + stands. +- The COM pitfalls page opened with "If you are an AI coding assistant + … read this page before touching any COM-related code", an instruction + to agents. It's ours and harmless, but `llms.txt` should describe, not + instruct, so that sentence moved to the second paragraph. +- No summary now addresses the reader as an agent or tells it to do + anything. + +**Offline run.** 402 links (219 relative) in the README, 60-odd pages and +`llms.txt`: no broken page, file or anchor. + +**First online run.** 145 URLs. Findings and what changed: + +- Every `andrewbartels1.github.io/SolidworksMCP-python/...` URL redirects + to `andrewbartels1.com/SolidworksMCP-python/...`, the custom domain set + on the owner's GitHub Pages site. Only the account owner can set that, + so it is listed in `SAME_SITE`. The owner may prefer to make + `andrewbartels1.com` the `site_url`; that's their call. +- `codecov.io` sends the badge link to `app.codecov.io`: subdomains now + count as the same site. +- `console.anthropic.com/settings/keys` now redirects to + `platform.claude.com`: the link was updated. +- 22 GitHub issue pages answered 429: they are now checked through the + API (above). +- `towardsdatascience.com` answers 403 to scripts and `www.solidworks.com` + never answers one; both are in `NOT_CHECKED` with the reason. The + checker does not pretend to be a browser to get past them. + +After those changes: 145 URLs, 143 visited and passing, 2 not checked. ## Risks / Trade-offs diff --git a/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md b/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md index f7d84b84..0fcb03ec 100644 --- a/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md +++ b/openspec/changes/own-llms-txt/specs/docs/link-check/spec.md @@ -18,7 +18,7 @@ The checks SHALL cover every link in `README.md`, every Markdown page under `doc ### Requirement: Links within the project are checked offline -On every test run, without network access, the check SHALL fail when a relative link (or a link to `site_url`) points at a page or file that does not exist, or at a `#anchor` that the target page has no heading or explicit `{#id}` for. Anchors SHALL be worked out the way the docs site makes them. +On every test run, without network access, the check SHALL fail when a relative link, a link to `site_url`, or a `/blob//` or `tree` link points at a page or file that does not exist, or at a `#anchor` that the target page has no heading or explicit `{#id}` for. Anchors SHALL be worked out the way the docs site makes them. #### Scenario: A moved page - **WHEN** a page links to `getting-started/old-name.md` and that file does not exist @@ -34,7 +34,7 @@ On every test run, without network access, the check SHALL fail when a relative ### Requirement: Links to other sites are checked online -A separate command SHALL visit every external URL once and fail when a URL does not answer with success, or when it redirects to a different site. A different site means a different host, with `www.` ignored; a link to this repository or the docs site that redirects anywhere outside them SHALL always fail. The command SHALL write a report listing every link, where it appears, the result and, for a redirect, where it went. Network trouble that is not the link's fault (a timeout) SHALL be retried before the link is failed. The command SHALL run after each docs deploy and once a week, and SHALL NOT run as part of the unit tests. +A separate command SHALL visit every external URL once and fail when a URL does not answer with success, or when it redirects to a different site. The same site means the same host with `www.` ignored, a subdomain of it (`codecov.io` to `app.codecov.io`), or a host listed with a reason as belonging to it (GitHub's content hosts; the custom domain the owner set for this project's GitHub Pages site). A GitHub issue or pull request link SHALL be checked through GitHub's API, which serves scripts, since the pages themselves rate-limit them. A site that refuses every script SHALL be listed with its reason, and the report SHALL show it as "not checked" rather than leave it out. The command SHALL write a report listing every link, where it appears, the result and, for a redirect, where it went. Network trouble that is not the link's fault (a timeout) SHALL be retried before the link is failed. The command SHALL run after each docs deploy and once a week, and SHALL NOT run as part of the unit tests. #### Scenario: A dead link - **WHEN** a URL answers 404, or its host does not resolve @@ -48,6 +48,14 @@ A separate command SHALL visit every external URL once and fail when a URL does - **WHEN** `https://www.microsoft.com/windows` redirects to `https://www.microsoft.com/en-us/windows` - **THEN** the link passes, and the report shows where it went +#### Scenario: A subdomain redirect +- **WHEN** `https://codecov.io/gh/owner/repo` redirects to `https://app.codecov.io/gh/owner/repo` +- **THEN** the link passes + +#### Scenario: A site that refuses scripts +- **WHEN** a URL's site is on the not-checked list +- **THEN** it is not visited, and the report lists it as "not checked" with the reason + #### Scenario: Every link is reported - **WHEN** the command finishes - **THEN** the report lists every external URL it visited, including the ones that passed, so a reader can see that every link was checked diff --git a/openspec/changes/own-llms-txt/tasks.md b/openspec/changes/own-llms-txt/tasks.md index 0ed585d6..bd39b759 100644 --- a/openspec/changes/own-llms-txt/tasks.md +++ b/openspec/changes/own-llms-txt/tasks.md @@ -1,40 +1,40 @@ ## 1. Reading the docs -- [ ] 1.1 `pyyaml` added to the `dev` and `test` extras; the `doc_links` package with `__init__.py` and its test package -- [ ] 1.2 `pages.py`: load `mkdocs.yml` with `!!python/...` tags ignored; walk `nav` into (section, nav title, path) in order, leaving out entries that aren't `.md` files in `docs/`; a page's URL from `site_url` with directory URLs; tests -- [ ] 1.3 A page's `# ` title and first prose paragraph (the skip rules in design decision 2; links reduced to their text; lines joined); a page with neither raises, naming it; tests for each skipped block kind -- [ ] 1.4 Heading ids: the toc slugify with `_1`, `_2` for repeats, plus `{#id}`; tests, and the parity test against `markdown.extensions.toc.slugify` over every docs heading (skipped without `markdown`) +- [x] 1.1 `pyyaml` added to the `dev` and `test` extras; the `doc_links` package with `__init__.py` and its test package +- [x] 1.2 `pages.py`: load `mkdocs.yml` with `!!python/...` tags ignored; walk `nav` into (section, nav title, path) in order, leaving out entries that aren't `.md` files in `docs/`; a page's URL from `site_url` with directory URLs; tests +- [x] 1.3 A page's `# ` title and first prose paragraph (the skip rules in design decision 2; links reduced to their text; lines joined); a page with neither raises, naming it; tests for each skipped block kind +- [x] 1.4 Heading ids: the toc slugify with `_1`, `_2` for repeats, plus `{#id}`; tests, and the parity test against `markdown.extensions.toc.slugify` over every docs heading (skipped without `markdown`) ## 2. llms.txt -- [ ] 2.1 `llms_txt.py` build: title and summary lines from `mkdocs.yml`, `## Overview` first, then the nav sections, entries in nav order; tests -- [ ] 2.2 The content rules shared by build and check: allowed URLs, line shapes, no `Cf`/`Cc` characters except `\n`, no HTML tag or comment; the builder names the page, the checker the line; tests for each rule -- [ ] 2.3 Check a committed text: stale (first differing line and the rebuild command); for an entry that differs, the page, the expected text and the text found; tests -- [ ] 2.4 `__main__.py` with `build`, `check`, `check-external`; exit codes; loguru output; tests +- [x] 2.1 `llms_txt.py` build: title and summary lines from `mkdocs.yml`, `## Overview` first, then the nav sections, entries in nav order; tests +- [x] 2.2 The content rules shared by build and check: allowed URLs, line shapes, no `Cf`/`Cc` characters except `\n`, no HTML tag or comment; the builder names the page, the checker the line; tests for each rule +- [x] 2.3 Check a committed text: stale (first differing line and the rebuild command); for an entry that differs, the page, the expected text and the text found; tests +- [x] 2.4 `__main__.py` with `build`, `check`, `check-external`; exit codes; loguru output; tests ## 3. Links -- [ ] 3.1 `links.py` finder: inline, reference-style, autolinks and images, each with file and line; nothing inside fenced or inline code; `mailto:` skipped; tests -- [ ] 3.2 Offline check: relative links from the page (README from the repo root), `site_url` links mapped to `docs/`, non-Markdown files must exist, anchors against the target's heading ids; tests for a missing page, a missing anchor, a good anchor, an image -- [ ] 3.3 Online check (design decision 6): one GET per unique URL, the same-host rule, our-URL rule, retries, concurrency, User-Agent; faked transport in the tests for 200, 404, DNS failure, timeout then success, same-host and cross-host redirects -- [ ] 3.4 The Markdown report at `tests/.generated/link-report.md` listing every URL with its result and locations; tests +- [x] 3.1 `links.py` finder: inline, reference-style, autolinks and images, each with file and line; nothing inside fenced or inline code; `mailto:` skipped; tests +- [x] 3.2 Offline check: relative links from the page (README from the repo root), `site_url` links mapped to `docs/`, non-Markdown files must exist, anchors against the target's heading ids; tests for a missing page, a missing anchor, a good anchor, an image +- [x] 3.3 Online check (design decision 6): one GET per unique URL, the same-host rule, our-URL rule, retries, concurrency, User-Agent; faked transport in the tests for 200, 404, DNS failure, timeout then success, same-host and cross-host redirects +- [x] 3.4 The Markdown report at `tests/.generated/link-report.md` listing every URL with its result and locations; tests ## 4. Run it on the real docs -- [ ] 4.1 Run the offline check on the README and docs; fix every broken link and anchor it finds, in the pages -- [ ] 4.2 Build `docs/llms.txt`; read every entry, and give each page whose opening reads badly (a "Last updated" line, a sentence ending in a colon, `docs/index.md`'s feedback note) a real opening paragraph, in the page; rebuild -- [ ] 4.3 Integration tests in `tests/integration/`: the committed `docs/llms.txt` matches a fresh build, and the offline check passes on the real docs -- [ ] 4.4 Run the online check by hand; fix or replace every dead or cross-site link it reports; record the counts in design decision 9 +- [x] 4.1 Run the offline check on the README and docs; fix every broken link and anchor it finds, in the pages +- [x] 4.2 Build `docs/llms.txt`; read every entry, and give each page whose opening reads badly (a "Last updated" line, a sentence ending in a colon, `docs/index.md`'s feedback note) a real opening paragraph, in the page; rebuild +- [x] 4.3 Integration tests in `tests/integration/`: the committed `docs/llms.txt` matches a fresh build, and the offline check passes on the real docs +- [x] 4.4 Run the online check by hand; fix or replace every dead or cross-site link it reports; record the counts in design decision 9 ## 5. CI and commands -- [ ] 5.1 `deploy-docs.yml`: a link-check job after `deploy`, and a weekly `schedule` that runs only that job; the report uploaded as an artifact -- [ ] 5.2 `dev-commands.ps1 dev-llms` / `dev-links` and `make llms` / `make links` -- [ ] 5.3 `mkdocs build --strict` copies `llms.txt` to the site root (checked in the built `site/`) +- [x] 5.1 `deploy-docs.yml`: a link-check job after `deploy`, and a weekly `schedule` that runs only that job; the report uploaded as an artifact +- [x] 5.2 `dev-commands.ps1 dev-llms` / `dev-links` and `make llms` / `make links` +- [x] 5.3 `mkdocs build --strict` copies `llms.txt` to the site root (checked in the built `site/`) ## 6. Docs, review and sign-off -- [ ] 6.1 CONTRIBUTING: a short note that `docs/llms.txt` is generated and how to rebuild it, and that page openings are its summaries; the CHANGELOG `Added` entries -- [ ] 6.2 Security review of the generated file (design decision 9): entry count, every URL ours, no hidden characters, no summary that reads as an instruction to an agent; recorded in the design -- [ ] 6.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`, `openspec validate --all` +- [x] 6.1 CONTRIBUTING: a short note that `docs/llms.txt` is generated and how to rebuild it, and that page openings are its summaries; the CHANGELOG `Added` entries +- [x] 6.2 Security review of the generated file (design decision 9): entry count, every URL ours, no hidden characters, no summary that reads as an instruction to an agent; recorded in the design +- [x] 6.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`, `openspec validate --all` - [ ] 6.4 Hand the user the file, the link report and the review (no live SolidWorks demo: nothing here touches SolidWorks); PR closing queue item 19, no attribution; archive and update the queue after the merge diff --git a/pyproject.toml b/pyproject.toml index 9d5006b6..23233515 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,6 +85,7 @@ dev = [ "tox>=4.11.0", "factory-boy>=3.3.0", "build>=1.0.0", # `python -m build`, used by `make build` + "pyyaml>=6.0", # solidworks_mcp.doc_links reads mkdocs.yml ] test = [ "pytest>=7.4.0", @@ -98,6 +99,7 @@ test = [ "fastapi>=0.115.0", "numpy>=1.26.0", "pypdfium2>=4.30.0", # live demos render each exported PDF into a frame + "pyyaml>=6.0", # solidworks_mcp.doc_links reads mkdocs.yml ] docs = [ # <2: MkDocs 2 is announced to drop support for existing themes, plugins diff --git a/src/solidworks_mcp/doc_links/__init__.py b/src/solidworks_mcp/doc_links/__init__.py new file mode 100644 index 00000000..db584248 --- /dev/null +++ b/src/solidworks_mcp/doc_links/__init__.py @@ -0,0 +1,12 @@ +"""The docs' own ``llms.txt``, and a check of every link in the docs. + +Run from a checkout:: + + python -m solidworks_mcp.doc_links build # write docs/llms.txt + python -m solidworks_mcp.doc_links check # offline: llms.txt and project links + python -m solidworks_mcp.doc_links check-external # online: every link to another site + +``llms.txt`` is built from the mkdocs nav: each entry's title and summary +are copied word for word from the page it links to, so nothing in it is +written by hand. Specs: ``docs/llms-txt`` and ``docs/link-check``. +""" diff --git a/src/solidworks_mcp/doc_links/__main__.py b/src/solidworks_mcp/doc_links/__main__.py new file mode 100644 index 00000000..c8d2a03d --- /dev/null +++ b/src/solidworks_mcp/doc_links/__main__.py @@ -0,0 +1,91 @@ +"""``python -m solidworks_mcp.doc_links build|check|check-external``. + +- ``build`` writes ``docs/llms.txt``. +- ``check`` (offline) checks ``docs/llms.txt`` against the docs and every + link to this project's own pages and files. +- ``check-external`` (online) visits every link to another site and writes + ``tests/.generated/link-report.md``. + +Each exits 1 when something fails. +""" + +from __future__ import annotations + +import argparse +import asyncio +import sys +from pathlib import Path + +from loguru import logger + +from .links import all_links, check_external, check_internal, is_external, report +from .llms_txt import LLMS_TXT, build, check +from .pages import DocsError, load_site + +#: Where ``check-external`` writes its report. +REPORT = Path("tests/.generated/link-report.md") + + +def main(argv: list[str] | None = None) -> int: + """Run one command. + + Args: + argv: The arguments (``sys.argv[1:]`` when omitted). + + Returns: + The exit code: 0 when it passed, 1 when it found a problem. + """ + parser = argparse.ArgumentParser(prog="python -m solidworks_mcp.doc_links") + parser.add_argument("command", choices=("build", "check", "check-external")) + parser.add_argument("--root", type=Path, default=Path.cwd(), help="repository root") + args = parser.parse_args(argv) + root: Path = args.root + if args.command == "build": + return _build(root) + if args.command == "check": + return _check(root) + return _check_external(root) + + +def _build(root: Path) -> int: + """Write ``docs/llms.txt``.""" + try: + text = build(root) + except DocsError as error: + logger.error(str(error)) + return 1 + (root / LLMS_TXT).write_text(text, encoding="utf-8", newline="\n") + logger.info(f"wrote {LLMS_TXT} ({text.count(chr(10) + '- [')} pages)") + return 0 + + +def _check(root: Path) -> int: + """The offline checks: ``llms.txt``, then every link within the project.""" + problems = check(root) + links = all_links(root) + problems += check_internal(root, load_site(root), links) + for problem in problems: + logger.error(problem) + internal = sum(1 for link in links if not is_external(link.target)) + logger.info( + f"{len(links)} links found, {internal} relative; {len(problems)} problems" + ) + return 1 if problems else 0 + + +def _check_external(root: Path) -> int: + """The online check, with its report written under ``tests/.generated/``.""" + results = asyncio.run(check_external(all_links(root))) + out = root / REPORT + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(report(results), encoding="utf-8", newline="\n") + failed = [r for r in results if not r.ok] + for result in failed: + went = f" -> {result.final_url}" if result.final_url else "" + logger.error(f"{result.url}: {result.detail}{went} ({', '.join(result.where)})") + logger.info(f"{len(results)} URLs visited, {len(failed)} failed; report: {REPORT}") + return 1 if failed else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/solidworks_mcp/doc_links/links.py b/src/solidworks_mcp/doc_links/links.py new file mode 100644 index 00000000..e0cb7cd7 --- /dev/null +++ b/src/solidworks_mcp/doc_links/links.py @@ -0,0 +1,502 @@ +"""Find every link in the README and the docs, and check it. + +- :func:`find_links` reads Markdown (and ``llms.txt``) and returns each + link with its file and line. Links in fenced or inline code are + examples, not links, and are left out, as are ``mailto:`` links. +- :func:`check_internal` checks, offline, links to this project's own + pages and files (relative links, ``site_url`` links and ``blob``/``tree`` + links into this repository), including ``#anchors``. +- :func:`check_external` visits every other URL once and fails a dead + link or a redirect to a different site (spec ``docs/link-check``). +""" + +from __future__ import annotations + +import asyncio +import os +import re +from collections.abc import Callable, Iterable +from dataclasses import dataclass, field +from pathlib import Path +from urllib.parse import unquote, urlsplit + +import httpx + +from .pages import Site, heading_ids, source_lines + +#: Files outside ``docs/`` that are checked. +EXTRA_FILES = ("README.md",) + +_CODE_SPAN = re.compile(r"(`+).+?\1") +_IMAGE = re.compile(r"!\[[^\[\]]*\]\(\s*]+)>?(?:\s+[\"'][^\"']*[\"'])?\s*\)") +_INLINE = re.compile(r"\[[^\[\]]*\]\(\s*]+)>?(?:\s+[\"'][^\"']*[\"'])?\s*\)") +_REF_DEF = re.compile(r"^\s{0,3}\[[^\]]+\]:\s*?(?:\s|$)") +_ANGLE = re.compile(r"<((?:https?)://[^>\s]+)>") +_HTML_ATTR = re.compile(r"""\b(?:href|src)=["']([^"']+)["']""") +_BARE = re.compile(r"(?()\[\]\"'`]+") + + +@dataclass(frozen=True) +class Link: + """One link and where it appears. + + Attributes: + file: The file it is in, relative to the repository root. + line: Its line number. + target: The link as written. + """ + + file: str + line: int + target: str + + +def checked_files(root: Path) -> list[Path]: + """The README, every Markdown page under ``docs/`` and ``docs/llms.txt``.""" + docs = root / "docs" + files = [root / name for name in EXTRA_FILES] + files += sorted(docs.rglob("*.md")) + llms = docs / "llms.txt" + if llms.is_file(): + files.append(llms) + return [f for f in files if f.is_file()] + + +def find_links(text: str, file: str) -> list[Link]: + """Every link in a Markdown text, outside code. + + Args: + text: The file's text. + file: Its path relative to the repository root. + + Returns: + The links, in file order. + """ + found: list[Link] = [] + for number, line, code in source_lines(text): + if code: + continue + plain = _CODE_SPAN.sub(lambda m: " " * len(m.group(0)), line) + targets: list[str] = [] + ref = _REF_DEF.match(plain) + if ref: + targets.append(ref.group(1)) + else: + # Images first, so a badge (an image inside a link) gives both. + targets += _IMAGE.findall(plain) + plain = _IMAGE.sub("IMAGE", plain) + targets += _INLINE.findall(plain) + targets += _ANGLE.findall(plain) + targets += _HTML_ATTR.findall(plain) + rest = _HTML_ATTR.sub(" ", _ANGLE.sub(" ", _INLINE.sub(" ", plain))) + targets += [t.rstrip(".,;:!?*_") for t in _BARE.findall(rest)] + found += [ + Link(file, number, target) + for target in targets + if target and not target.lower().startswith("mailto:") + ] + return found + + +def all_links(root: Path) -> list[Link]: + """Every link in every checked file under ``root``.""" + links: list[Link] = [] + for path in checked_files(root): + rel = path.relative_to(root).as_posix() + links += find_links(path.read_text(encoding="utf-8"), rel) + return links + + +def is_external(target: str) -> bool: + """Whether a link names a scheme (``https://...``) rather than a path.""" + return bool(re.match(r"^[a-z][a-z0-9+.-]*:", target, re.IGNORECASE)) + + +# --------------------------------------------------------------------------- +# Offline + + +def check_internal(root: Path, site: Site, links: Iterable[Link]) -> list[str]: + """Problems with links to this project's own pages and files. + + Relative links resolve from the linking file; ``site_url`` links map + back to ``docs/``; ``/blob|tree//`` links map to + the checkout. Links to other sites are left to :func:`check_external`. + + Args: + root: The repository root. + site: The site settings. + links: The links to check. + + Returns: + ``file:line: problem`` messages; empty when every link resolves. + """ + ids: dict[Path, set[str]] = {} + problems: list[str] = [] + for link in links: + resolved = _local_target(root, site, link) + if resolved is None: + continue + path, anchor = resolved + where = f"{link.file}:{link.line}" + if not path.exists(): + problems.append( + f"{where}: {link.target}: no such file ({_rel(root, path)})" + ) + continue + if path.is_dir(): + path = _index_of(path) + if path is None: + continue + if anchor and path.suffix == ".md": + if path not in ids: + ids[path] = heading_ids(path.read_text(encoding="utf-8")) + if anchor not in ids[path]: + problems.append( + f"{where}: {link.target}: {_rel(root, path)} has no heading " + f"or id `{anchor}`" + ) + return problems + + +def _rel(root: Path, path: Path) -> str: + """``path`` relative to ``root`` when it is inside it.""" + try: + return path.resolve().relative_to(root.resolve()).as_posix() + except ValueError: + return path.as_posix() + + +def _index_of(directory: Path) -> Path | None: + """The page a directory link opens: its ``index.md`` or ``README.md``.""" + for name in ("index.md", "README.md"): + if (directory / name).is_file(): + return directory / name + return None + + +def _local_target(root: Path, site: Site, link: Link) -> tuple[Path, str] | None: + """The file (and anchor) a link points at in the checkout, or ``None``. + + ``None`` means the link isn't this project's to check offline: another + site, the generated API reference, or a repository page that isn't a + file (issues, pull requests, actions). + """ + target = link.target + if target.startswith(site.url + "/") or target == site.url: + return _site_target(root, site, target) + if target.startswith(site.repo_url + "/"): + return _repo_target(root, site, target) + if is_external(target): + return None + path_part, _, anchor = target.partition("#") + base = (root / link.file).parent + if not path_part: + return root / link.file, anchor + path_part = unquote(path_part.split("?")[0]) + if path_part.startswith("/"): + return root / path_part.lstrip("/"), anchor + if link.file.startswith("docs/") and _is_api(base / path_part, root): + return None + return (base / path_part).resolve(), anchor + + +def _is_api(path: Path, root: Path) -> bool: + """Whether ``path`` is under the generated ``docs/api/`` reference.""" + rel = _rel(root, path) + return rel == "docs/api" or rel.startswith("docs/api/") + + +def _site_target(root: Path, site: Site, url: str) -> tuple[Path, str] | None: + """A ``site_url`` link mapped back to the page or file in ``docs/``.""" + parts = urlsplit(url) + rest = unquote(parts.path)[len(urlsplit(site.url).path) :].strip("/") + docs = root / "docs" + if rest == "api" or rest.startswith("api/"): + return None + if not rest: + return docs / "index.md", parts.fragment + for candidate in (docs / rest, docs / f"{rest}.md", docs / rest / "index.md"): + if candidate.is_file(): + return candidate, parts.fragment + return docs / rest, parts.fragment + + +def _repo_target(root: Path, site: Site, url: str) -> tuple[Path, str] | None: + """A ``/blob|tree//`` link mapped to the checkout.""" + parts = urlsplit(url) + rest = unquote(parts.path)[len(urlsplit(site.repo_url).path) :].strip("/") + match = re.match(r"^(?:blob|tree)/[^/]+/(.+)$", rest) + if not match: + return None + return root / match.group(1), parts.fragment + + +# --------------------------------------------------------------------------- +# Online + + +@dataclass +class Result: + """What visiting one URL found. + + Attributes: + url: The URL as written. + ok: Whether it passed. + detail: The status, or what went wrong. + final_url: Where redirects ended, when they moved it. + where: Every ``file:line`` it appears on. + """ + + url: str + ok: bool + detail: str + final_url: str | None = None + where: list[str] = field(default_factory=list) + + +def _host(url: str) -> str: + """The URL's host, lowercase, without a leading ``www.``.""" + return (urlsplit(url).hostname or "").lower().removeprefix("www.") + + +#: Hosts a site legitimately hands its pages to. GitHub serves release +#: downloads, raw files and avatars from its content hosts; GitHub Pages +#: sends ``.github.io`` to the custom domain the owner set on their +#: Pages site, which only the owner can configure. +SAME_SITE: dict[str, tuple[str, ...]] = { + "github.com": ( + "objects.githubusercontent.com", + "raw.githubusercontent.com", + "release-assets.githubusercontent.com", + "avatars.githubusercontent.com", + ), + "andrewbartels1.github.io": ("andrewbartels1.com",), +} + +#: URLs (by prefix) a script can't check, and why. The report lists each +#: as "not checked" with its reason; nothing is skipped silently. +NOT_CHECKED: dict[str, str] = { + "https://towardsdatascience.com/": ( + "answers 403 to any script; a reference article, check it by hand" + ), + "https://www.solidworks.com/": ( + "never answers a script (times out); the vendor's home page" + ), +} + +_GITHUB_ITEM = re.compile( + r"^https://github\.com/([\w.-]+)/([\w.-]+)/(?:issues|pull)/(\d+)/?$" +) + + +def api_probe(url: str) -> str | None: + """The GitHub API URL that answers for a GitHub issue or pull request page. + + GitHub rate-limits scripts reading its issue pages (HTTP 429) but serves + its API to them; the issues endpoint answers for pull requests too. + + Args: + url: A link. + + Returns: + The API URL, or ``None`` when ``url`` isn't an issue or PR page. + """ + match = _GITHUB_ITEM.match(url) + if not match: + return None + owner, repo, number = match.groups() + return f"https://api.github.com/repos/{owner}/{repo}/issues/{number}" + + +def github_headers(environ: dict[str, str]) -> dict[str, str]: + """The headers for GitHub API calls: the CI token when one is set. + + Args: + environ: The environment (``GITHUB_TOKEN`` or ``GH_TOKEN``). + + Returns: + An ``Authorization`` header, or nothing. + """ + token = environ.get("GITHUB_TOKEN") or environ.get("GH_TOKEN") + return {"Authorization": f"Bearer {token}"} if token else {} + + +def same_site(url: str, final: str) -> bool: + """Whether a redirect from ``url`` to ``final`` stays on the same site. + + Args: + url: The URL as written. + final: Where its redirects ended. + + Returns: + True when the hosts match (``www.`` ignored), one is a subdomain of + the other (``codecov.io`` -> ``app.codecov.io``), or ``final`` is one + of the hosts :data:`SAME_SITE` lists for ``url``'s host. + """ + start, end = _host(url), _host(final) + if start == end or end in SAME_SITE.get(start, ()): + return True + return end.endswith("." + start) or start.endswith("." + end) + + +_RETRY_STATUS = {429, 500, 502, 503, 504} + + +async def visit( + client: httpx.AsyncClient, + url: str, + *, + attempts: int = 4, + pause: float = 2.0, + sleep: Callable[[float], object] = asyncio.sleep, + probe: str | None = None, + headers: dict[str, str] | None = None, +) -> Result: + """Visit one URL and judge it. + + A GET follows redirects. It passes on a 2xx that ended on the same + site. Timeouts, dropped connections, 429 and 5xx are retried up to + ``attempts`` times; any other failure is final at once. + + Args: + client: The HTTP client (redirects followed). + url: The URL to visit. + attempts: How many tries before a retryable failure is final. + pause: Seconds before the first retry; doubled each time. + sleep: The pause function (tests pass one that doesn't wait). + probe: A URL to request instead of ``url`` (see :func:`api_probe`). + headers: Extra request headers (sent only to ``probe``). + + Returns: + The result. + """ + detail = "" + target = probe or url + via = " (GitHub API)" if probe else "" + for attempt in range(attempts): + if attempt: + await sleep(pause * 2 ** (attempt - 1)) # type: ignore[misc] + try: + response = await client.get(target, headers=headers or {}) + except ( + httpx.TimeoutException, + httpx.RemoteProtocolError, + httpx.ReadError, + ) as error: + detail = f"{type(error).__name__} (tried {attempt + 1} times)" + continue + except httpx.HTTPError as error: + return Result(url, False, f"{type(error).__name__}: {error}") + final = str(response.url) + moved = final if final.rstrip("/") != target.rstrip("/") else None + if response.status_code in _RETRY_STATUS: + detail = f"HTTP {response.status_code} (tried {attempt + 1} times)" + wait = _retry_after(response) + if wait and attempt + 1 < attempts: + await sleep(wait) # type: ignore[misc] + continue + if not response.is_success: + return Result(url, False, f"HTTP {response.status_code}{via}", moved) + if moved and not same_site(target, final): + return Result(url, False, "redirects to another site", moved) + return Result(url, True, f"HTTP {response.status_code}{via}", moved) + return Result(url, False, detail) + + +def _retry_after(response: httpx.Response) -> float: + """Seconds a 429/503 asks to wait (``Retry-After``), at most 60; else 0.""" + value = response.headers.get("retry-after", "") + return min(float(value), 60.0) if value.isdigit() else 0.0 + + +USER_AGENT = "SolidworksMCP-python docs link check (+https://github.com/andrewbartels1/SolidworksMCP-python)" + + +async def check_external( + links: Iterable[Link], + *, + transport: httpx.AsyncBaseTransport | None = None, + concurrency: int = 8, + per_host: int = 2, + timeout: float = 30.0, + pause: float = 2.0, +) -> list[Result]: + """Visit every external URL once, eight at a time. + + Args: + links: The links; those that aren't ``http(s)`` URLs are skipped. + transport: An httpx transport (tests pass a mock one). + concurrency: How many URLs are visited at once. + per_host: How many at once on one host (GitHub answers 429 to more). + timeout: Seconds per request. + pause: Seconds before the first retry. + + Returns: + One result per unique URL, sorted by URL, each listing where it + appears. + """ + where: dict[str, list[str]] = {} + for link in links: + if re.match(r"^https?://", link.target, re.IGNORECASE): + where.setdefault(link.target, []).append(f"{link.file}:{link.line}") + api_headers = github_headers(dict(os.environ)) + gate = asyncio.Semaphore(concurrency) + hosts: dict[str, asyncio.Semaphore] = {} + async with httpx.AsyncClient( + follow_redirects=True, + timeout=timeout, + transport=transport, + headers={"User-Agent": USER_AGENT}, + ) as client: + + async def one(url: str) -> Result: + reason = next( + (why for prefix, why in NOT_CHECKED.items() if url.startswith(prefix)), + None, + ) + if reason is not None: + return Result(url, True, f"not checked: {reason}", where=where[url]) + probe = api_probe(url) + host = hosts.setdefault(_host(probe or url), asyncio.Semaphore(per_host)) + async with gate, host: + result = await visit( + client, + url, + pause=pause, + probe=probe, + headers=api_headers if probe else None, + ) + result.where = where[url] + return result + + results = await asyncio.gather(*(one(url) for url in sorted(where))) + return list(results) + + +def report(results: list[Result]) -> str: + """The Markdown report: a count, then every URL with its result. + + Args: + results: The results of :func:`check_external`. + + Returns: + The report's text. + """ + failed = [r for r in results if not r.ok] + lines = [ + "# Link report", + "", + f"{len(results)} external URLs visited: {len(results) - len(failed)} passed, " + f"{len(failed)} failed.", + "", + "| Result | URL | Went to | Where |", + "| --- | --- | --- | --- |", + ] + for result in sorted(results, key=lambda r: (r.ok, r.url)): + mark = "pass" if result.ok else "**FAIL**" + lines.append( + f"| {mark}: {result.detail} | {result.url} | {result.final_url or ''} | " + f"{', '.join(result.where)} |" + ) + return "\n".join(lines) + "\n" diff --git a/src/solidworks_mcp/doc_links/llms_txt.py b/src/solidworks_mcp/doc_links/llms_txt.py new file mode 100644 index 00000000..453ed23d --- /dev/null +++ b/src/solidworks_mcp/doc_links/llms_txt.py @@ -0,0 +1,243 @@ +"""Build ``docs/llms.txt`` from the docs, and check a committed copy. + +The file follows the llms.txt format: a ``# `` title, a ``> `` summary, +then ``## `` sections of ``- [title](url): summary`` entries. Every title +and summary is copied word for word from the page it links to (see +:func:`.pages.opening`), and the same content rules hold for the builder +and the checker, so a hand edit can't match a bad build. +""" + +from __future__ import annotations + +import re +import unicodedata +from dataclasses import dataclass +from pathlib import Path + +from .pages import DocsError, Site, load_site, nav_pages, opening, page_url + +#: Where the file lives (MkDocs copies it to the site root). +LLMS_TXT = Path("docs/llms.txt") +#: The command that rebuilds it. +BUILD_COMMAND = "python -m solidworks_mcp.doc_links build" + +_ENTRY = re.compile(r"^- \[(?P[^\]]+)\]\((?P<url>\S+)\): (?P<summary>\S.*)$") +_SHAPES = ( + re.compile(r"^# \S.*$"), + re.compile(r"^> \S.*$"), + re.compile(r"^## \S.*$"), + _ENTRY, + re.compile(r"^$"), +) +_URL = re.compile(r"[a-z][a-z0-9+.-]*://[^\s)>\]]+", re.IGNORECASE) +_CODE_SPAN = re.compile(r"(`+).+?\1") +_HTML = re.compile(r"<(?:[A-Za-z/]|!--)") + + +@dataclass(frozen=True) +class Entry: + """One page's line in ``llms.txt``. + + Attributes: + section: Its ``## `` section. + page: The page's path under ``docs/``. + title: The page's title. + url: The page's published URL. + summary: The page's opening paragraph. + """ + + section: str + page: str + title: str + url: str + summary: str + + @property + def line(self) -> str: + """The entry as it appears in the file.""" + return f"- [{self.title}]({self.url}): {self.summary}" + + +def entries(root: Path, site: Site | None = None) -> list[Entry]: + """Every nav page's entry, in nav order. + + Args: + root: The repository root. + site: The site settings, read from ``mkdocs.yml`` when omitted. + + Returns: + The entries. + + Raises: + DocsError: When a page has no title or opening paragraph, or its + title or opening breaks a content rule. + """ + site = site or load_site(root) + docs = root / "docs" + found: list[Entry] = [] + for page in nav_pages(site.nav, docs): + start = opening((docs / page.path).read_text(encoding="utf-8"), page.path) + entry = Entry( + page.section, + page.path, + start.title, + page_url(site.url, page.path), + start.summary, + ) + problems = line_problems(entry.line, site) + if problems: + raise DocsError(f"{page.path}: {problems[0]}") + found.append(entry) + return found + + +def build(root: Path) -> str: + """The text of ``llms.txt`` for the docs under ``root``. + + Args: + root: The repository root. + + Returns: + The file's text, ending in a newline. + + Raises: + DocsError: As :func:`entries`, or when the site name or + description breaks a content rule. + """ + site = load_site(root) + lines = [f"# {site.name}", "", f"> {site.description}"] + section = None + for entry in entries(root, site): + if entry.section != section: + section = entry.section + lines += ["", f"## {section}", ""] + lines.append(entry.line) + for line in lines[:3]: + problems = line_problems(line, site) + if problems: + raise DocsError(f"mkdocs.yml: {problems[0]}") + return "\n".join(lines) + "\n" + + +def line_problems(line: str, site: Site) -> list[str]: + """What is wrong with one line of ``llms.txt``, if anything. + + The rules (spec ``docs/llms-txt``): one of the allowed shapes; every URL + under ``site_url`` or ``repo_url``; no control or format characters + (zero-width, byte-order mark, bidirectional controls); no HTML tag or + comment outside code spans. + + Args: + line: The line, without its line break. + site: The site settings (for the allowed URLs). + + Returns: + A message per problem; empty when the line is fine. + """ + problems: list[str] = [] + for char in line: + if unicodedata.category(char) in ("Cc", "Cf"): + problems.append( + f"hidden character U+{ord(char):04X} " + f"({unicodedata.name(char, 'unnamed')})" + ) + if _HTML.search(_CODE_SPAN.sub("", line)): + problems.append("HTML tag or comment") + for url in _URL.findall(line): + if not _ours(url, site): + problems.append(f"link outside this project: {url}") + if not any(shape.match(line) for shape in _SHAPES): + problems.append("not a title, summary, section, entry or blank line") + return problems + + +def _ours(url: str, site: Site) -> bool: + """Whether ``url`` is the docs site or this repository.""" + return any( + url == base or url.startswith(base + "/") for base in (site.url, site.repo_url) + ) + + +def check(root: Path, committed: str | None = None) -> list[str]: + """Problems with the committed ``llms.txt``; empty when it is right. + + Args: + root: The repository root. + committed: The file's text; read from ``docs/llms.txt`` when omitted. + + Returns: + One message per problem: a content rule broken (with its line + number), an entry whose title or summary differs from its page + (with the expected and the found text), a page missing or extra, + or else the first line that differs. Each ends by naming the + rebuild command when the fix is a rebuild. + """ + site = load_site(root) + if committed is None: + path = root / LLMS_TXT + if not path.is_file(): + return [f"{LLMS_TXT} is missing; run `{BUILD_COMMAND}`"] + committed = path.read_text(encoding="utf-8") + problems = [ + f"{LLMS_TXT}:{number}: {problem}" + for number, line in enumerate(committed.split("\n"), start=1) + for problem in line_problems(line, site) + ] + try: + expected = build(root) + except DocsError as error: + return [*problems, str(error)] + if committed == expected: + return problems + problems += _entry_differences(committed, entries(root, site)) + if not problems: + problems.append(_first_difference(committed, expected)) + return problems + + +def _entry_differences(committed: str, expected: list[Entry]) -> list[str]: + """Entries whose title or summary differs from the page, or are missing/extra.""" + found: dict[str, tuple[int, str, str]] = {} + for number, line in enumerate(committed.split("\n"), start=1): + match = _ENTRY.match(line) + if match: + found[match["url"]] = (number, match["title"], match["summary"]) + problems: list[str] = [] + for entry in expected: + if entry.url not in found: + problems.append( + f"{LLMS_TXT}: no entry for {entry.page}; run `{BUILD_COMMAND}`" + ) + continue + number, title, summary = found.pop(entry.url) + for field, want, got in ( + ("title", entry.title, title), + ("summary", entry.summary, summary), + ): + if want != got: + problems.append( + f"{LLMS_TXT}:{number}: the {field} doesn't match {entry.page}\n" + f" expected: {want}\n found: {got}" + ) + for url, (number, _title, _summary) in found.items(): + problems.append( + f"{LLMS_TXT}:{number}: {url} is not a page in the nav; " + f"run `{BUILD_COMMAND}`" + ) + return problems + + +def _first_difference(committed: str, expected: str) -> str: + """The first line where the committed file and a fresh build differ.""" + have, want = committed.split("\n"), expected.split("\n") + for number, (got, line) in enumerate(zip(have, want, strict=False), start=1): + if got != line: + return ( + f"{LLMS_TXT}:{number}: out of date (expected {line!r}, found " + f"{got!r}); run `{BUILD_COMMAND}`" + ) + return ( + f"{LLMS_TXT}:{min(len(have), len(want)) + 1}: out of date (the file is " + f"{'longer' if len(have) > len(want) else 'shorter'} than a fresh build); " + f"run `{BUILD_COMMAND}`" + ) diff --git a/src/solidworks_mcp/doc_links/pages.py b/src/solidworks_mcp/doc_links/pages.py new file mode 100644 index 00000000..e7691f85 --- /dev/null +++ b/src/solidworks_mcp/doc_links/pages.py @@ -0,0 +1,391 @@ +"""Read the docs: the mkdocs nav, and each page's title, opening and anchors. + +Everything here reads Markdown source; nothing renders it. The rules for +what counts as a page's opening paragraph are in the ``docs/llms-txt`` +spec, and heading ids follow Python-Markdown's ``toc`` extension, which +the docs site uses. +""" + +from __future__ import annotations + +import re +import unicodedata +from collections.abc import Iterator +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +import yaml + +#: The section that holds the nav's top-level pages. +OVERVIEW = "Overview" + + +class DocsError(Exception): + """A page can't give what ``llms.txt`` needs from it (names the page).""" + + +class _MkDocsLoader(yaml.SafeLoader): + """A safe loader that reads ``!!python/...`` tags as ``None``. + + ``mkdocs.yml`` names Python callables for some Markdown extensions; + only the site settings and the nav are needed here, so those tags are + read as nothing instead of importing anything. + """ + + +def _ignore_tag(loader: yaml.SafeLoader, suffix: str, node: yaml.Node) -> None: + """Read a tagged node as ``None``.""" + return None + + +_MkDocsLoader.add_multi_constructor("tag:yaml.org,2002:python/", _ignore_tag) + + +@dataclass(frozen=True) +class Site: + """The settings ``llms.txt`` and the link checks use. + + Attributes: + name: ``site_name``. + description: ``site_description``. + url: ``site_url``, without a trailing slash. + repo_url: ``repo_url``, without a trailing slash. + nav: The nav as written in ``mkdocs.yml``. + """ + + name: str + description: str + url: str + repo_url: str + nav: list[Any] + + +def load_site(root: Path) -> Site: + """Read ``mkdocs.yml`` under ``root``. + + Args: + root: The repository root. + + Returns: + The site settings and nav. + """ + text = (root / "mkdocs.yml").read_text(encoding="utf-8") + config = yaml.load(text, Loader=_MkDocsLoader) # noqa: S506 - a SafeLoader subclass + return Site( + name=config["site_name"], + description=config["site_description"], + url=config["site_url"].rstrip("/"), + repo_url=config["repo_url"].rstrip("/"), + nav=config["nav"], + ) + + +@dataclass(frozen=True) +class NavPage: + """A Markdown page listed in the nav. + + Attributes: + section: The top-level nav section it is under (``Overview`` for + top-level pages). + path: Its path relative to ``docs/``, with forward slashes. + """ + + section: str + path: str + + +def nav_pages(nav: list[Any], docs_dir: Path) -> list[NavPage]: + """The nav's Markdown pages, in nav order. + + Entries that are not ``.md`` files in ``docs_dir`` (the generated API + reference, for one) are left out. + + Args: + nav: The nav from ``mkdocs.yml``. + docs_dir: The ``docs/`` directory. + + Returns: + One entry per page; top-level pages first, under ``Overview``. + """ + top: list[NavPage] = [] + sections: list[NavPage] = [] + for item in nav: + for title, value in _entries(item): + if isinstance(value, list): + sections.extend(NavPage(title, path) for path in _paths(value)) + elif isinstance(value, str): + top.append(NavPage(OVERVIEW, value)) + return [p for p in top + sections if _is_page(p.path, docs_dir)] + + +def _entries(item: Any) -> Iterator[tuple[str, Any]]: + """The (title, value) pairs of one nav item (a bare path has no title).""" + if isinstance(item, dict): + yield from item.items() + else: + yield "", item + + +def _paths(items: list[Any]) -> Iterator[str]: + """Every page path in a nav section, nested sections included, in order.""" + for item in items: + for _title, value in _entries(item): + if isinstance(value, list): + yield from _paths(value) + elif isinstance(value, str): + yield value + + +def _is_page(path: str, docs_dir: Path) -> bool: + """Whether ``path`` is a Markdown file in ``docs_dir``.""" + return path.endswith(".md") and (docs_dir / path).is_file() + + +def page_url(site_url: str, path: str) -> str: + """The published URL of the page at ``path`` (directory URLs). + + Args: + site_url: ``site_url`` without a trailing slash. + path: The page's path relative to ``docs/``. + + Returns: + ``index.md`` -> ``<site_url>/``; ``a/b.md`` -> ``<site_url>/a/b/``; + ``a/index.md`` -> ``<site_url>/a/``. + """ + stem = path.removesuffix(".md") + if stem == "index": + return f"{site_url}/" + stem = stem.removesuffix("/index") + return f"{site_url}/{stem}/" + + +# --------------------------------------------------------------------------- +# Markdown source + + +_FENCE = re.compile(r"^\s*(```|~~~)") +_HEADING = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$") +_ATTRS = re.compile(r"\s*\{([^{}]*)\}\s*$") +_ATTR_ID = re.compile(r"\{:?[^{}]*#([\w-]+)[^{}]*\}") +_HTML_ID = re.compile(r"""(?<![\w-])id=["']([\w-]+)["']""") +_FRONT_MATTER = re.compile(r"\A---\n.*?\n---\n", re.DOTALL) + + +def source_lines(text: str) -> list[tuple[int, str, bool]]: + """The page's lines as (line number, text, inside a fenced code block). + + Front matter, if any, is blanked out (its lines kept so line numbers + still match the file). Fence lines themselves count as code. + + Args: + text: The page's Markdown. + + Returns: + One tuple per line, numbered from 1. + """ + front = _FRONT_MATTER.match(text) + if front: + blank = "\n" * front.group(0).count("\n") + text = blank + text[front.end() :] + lines: list[tuple[int, str, bool]] = [] + fence: str | None = None + for number, line in enumerate(text.splitlines(), start=1): + opened = _FENCE.match(line) + if fence is None and opened: + fence = opened.group(1) + lines.append((number, line, True)) + elif fence is not None: + if line.strip().startswith(fence): + fence = None + lines.append((number, line, True)) + else: + lines.append((number, line, False)) + return lines + + +def _split_attrs(text: str) -> tuple[str, str | None]: + """Split a heading's trailing ``{#id .class}`` off; return (text, id).""" + attrs = _ATTRS.search(text) + if not attrs: + return text, None + ids = re.findall(r"#([\w-]+)", attrs.group(1)) + return text[: attrs.start()], (ids[0] if ids else None) + + +@dataclass(frozen=True) +class Opening: + """A page's title and opening paragraph. + + Attributes: + title: The ``# `` heading, as written (attributes removed). + summary: The first prose paragraph, links reduced to their text, + lines joined with single spaces. + """ + + title: str + summary: str + + +_NOT_PROSE = re.compile( + r"^\s*(>|!!!|\?\?\?|===|[-*+]\s|\d+[.)]\s|\||<|!\[|\[!\[|---|\*\*\*|___|:::)" +) + + +def opening(text: str, page: str) -> Opening: + """The page's ``# `` title and its first prose paragraph. + + Prose is a paragraph before the first lower heading that is not a + blockquote, admonition, list, table, image, badge line, HTML, rule or + code (fenced or indented). + + Args: + text: The page's Markdown. + page: The page's path, for the error message. + + Returns: + The title and summary. + + Raises: + DocsError: When the page has no ``# `` heading, or no prose + paragraph before its next heading. + """ + lines = source_lines(text) + title: str | None = None + block: list[str] = [] + for _number, line, code in lines: + heading = None if code else _HEADING.match(line) + if title is None: + if heading and len(heading.group(1)) == 1: + title = _split_attrs(heading.group(2))[0] + continue + if heading: + break + if code or line.strip() == "": + if _is_prose(block): + return Opening(title, _inline_text(" ".join(block))) + block = [] + continue + block.append(line.strip() if block else line) + if title is None: + raise DocsError(f"{page}: no `# ` heading to use as its title") + if _is_prose(block): + return Opening(title, _inline_text(" ".join(block))) + raise DocsError( + f"{page}: no opening paragraph after its `# ` heading (a blockquote, " + "list, table, image or code doesn't count); give the page one" + ) + + +def _is_prose(block: list[str]) -> bool: + """Whether a paragraph's lines (first line unstripped) are prose.""" + if not block: + return False + first = block[0] + if first.startswith((" ", "\t")): + return False + return not _NOT_PROSE.match(first) + + +_CODE_SPAN = re.compile(r"(`+)(.+?)\1") +_IMAGE = re.compile(r"!\[([^\]]*)\]\([^)]*\)") +_INLINE_LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)") +_REF_LINK = re.compile(r"\[([^\]]+)\]\[[^\]]*\]") +_AUTOLINK = re.compile(r"<((?:https?|mailto):[^>\s]+)>") + + +def _inline_text(text: str) -> str: + """Reduce links and images to their text, leaving code spans as written. + + Code spans are set aside first, so link syntax inside one is kept, and + a link whose text is a code span (``[`x.py`](x.py)``) becomes the span. + """ + spans: list[str] = [] + + def hold(match: re.Match[str]) -> str: + spans.append(match.group(0)) + return f"\x00{len(spans) - 1}\x00" + + held = _strip_links(_CODE_SPAN.sub(hold, text)) + restored = re.sub("\x00(\\d+)\x00", lambda m: spans[int(m.group(1))], held) + return re.sub(r"\s+", " ", restored).strip() + + +def _strip_links(text: str) -> str: + """Links and images in plain (non-code) text, reduced to their text.""" + text = _IMAGE.sub(r"\1", text) + text = _INLINE_LINK.sub(r"\1", text) + text = _REF_LINK.sub(r"\1", text) + return _AUTOLINK.sub(r"\1", text) + + +# --------------------------------------------------------------------------- +# Heading ids + + +def slugify(value: str, separator: str = "-") -> str: + """Python-Markdown's default ``toc`` slugify, without needing ``markdown``. + + Args: + value: The heading's text. + separator: What spaces and hyphens become. + + Returns: + The heading's id. + """ + value = unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode() + value = re.sub(r"[^\w\s-]", "", value).strip().lower() + return re.sub(rf"[{separator}\s]+", separator, value) + + +def heading_text(raw: str) -> str: + """A heading's text as the ``toc`` extension sees it, before slugifying. + + Links become their text, code spans their content, and emphasis + markers and HTML tags go. + + Args: + raw: The heading as written, attributes removed. + + Returns: + Its plain text. + """ + text = _strip_links(raw) + text = _CODE_SPAN.sub(r"\2", text) + text = re.sub(r"<[^>]+>", "", text) + return re.sub(r"(\*\*|__|\*)", "", text) + + +def heading_ids(text: str) -> set[str]: + """Every anchor the page's headings get, and every ``{#id}`` it sets. + + Repeated slugs get ``_1``, ``_2`` in page order, as the ``toc`` + extension makes them. + + Args: + text: The page's Markdown. + + Returns: + The ids. + """ + ids: set[str] = set() + for _number, line, code in source_lines(text): + if code: + continue + heading = _HEADING.match(line) + if heading: + raw, explicit = _split_attrs(heading.group(2)) + ids.add(explicit or _unique(slugify(heading_text(raw)), ids)) + else: + ids.update(_ATTR_ID.findall(line)) + ids.update(_HTML_ID.findall(line)) + return ids + + +def _unique(slug: str, taken: set[str]) -> str: + """``slug``, or ``slug_1``, ``slug_2``, ... when it is already taken.""" + candidate, n = slug, 0 + while candidate in taken: + n += 1 + candidate = f"{slug}_{n}" + return candidate diff --git a/tests/integration/test_llms_txt_up_to_date.py b/tests/integration/test_llms_txt_up_to_date.py new file mode 100644 index 00000000..383c2502 --- /dev/null +++ b/tests/integration/test_llms_txt_up_to_date.py @@ -0,0 +1,28 @@ +"""The committed llms.txt matches the docs, and every project link resolves. + +Specs: docs/llms-txt and docs/link-check (the offline half). Editing a +page's title or opening paragraph, or the nav, changes ``docs/llms.txt``; +rebuild it with ``python -m solidworks_mcp.doc_links build``. +""" + +from __future__ import annotations + +from pathlib import Path + +from solidworks_mcp.doc_links.links import all_links, check_internal +from solidworks_mcp.doc_links.llms_txt import check +from solidworks_mcp.doc_links.pages import load_site + +_ROOT = Path(__file__).resolve().parents[2] + + +def test_llms_txt_matches_the_docs_word_for_word() -> None: + problems = check(_ROOT) + + assert problems == [], "\n".join(problems) + + +def test_every_link_within_the_project_resolves() -> None: + problems = check_internal(_ROOT, load_site(_ROOT), all_links(_ROOT)) + + assert problems == [], "\n".join(problems) diff --git a/tests/solidworks_mcp/doc_links/__init__.py b/tests/solidworks_mcp/doc_links/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/solidworks_mcp/doc_links/conftest.py b/tests/solidworks_mcp/doc_links/conftest.py new file mode 100644 index 00000000..a634d711 --- /dev/null +++ b/tests/solidworks_mcp/doc_links/conftest.py @@ -0,0 +1,55 @@ +"""A small docs site on disk for the ``doc_links`` tests.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +SITE = "https://example.github.io/proj" +REPO = "https://github.com/owner/proj" + +MKDOCS = f"""\ +site_name: Proj +site_url: {SITE}/ +site_description: A test project +repo_url: {REPO} +markdown_extensions: + - pymdownx.superfences: + custom_fences: + - name: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format +nav: + - Home: index.md + - Guide: + - Start: guide/start.md + - Deeper: + - More: guide/more.md + - Missing: guide/missing.md + - API Reference: api/ +""" + +PAGES = { + "index.md": "# Proj\n\nProj does a thing. See [the guide](guide/start.md).\n", + "guide/start.md": ( + "---\ntitle: x\n---\n# Start here {#top}\n\n> A note first.\n\n" + "Start with `uv`, then\nread [more](more.md#details).\n\n## Details\n" + ), + "guide/more.md": "# More\n\nMore words.\n\n## Details\n\n## Details\n", +} + + +def write_site(root: Path, pages: dict[str, str] | None = None) -> Path: + """Write ``mkdocs.yml`` and the pages under ``root``; return ``root``.""" + (root / "mkdocs.yml").write_text(MKDOCS, encoding="utf-8") + for name, text in (PAGES if pages is None else pages).items(): + path = root / "docs" / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + return root + + +@pytest.fixture +def site_root(tmp_path: Path) -> Path: + """A repository root holding the small site.""" + return write_site(tmp_path) diff --git a/tests/solidworks_mcp/doc_links/test___main__.py b/tests/solidworks_mcp/doc_links/test___main__.py new file mode 100644 index 00000000..b6e20492 --- /dev/null +++ b/tests/solidworks_mcp/doc_links/test___main__.py @@ -0,0 +1,88 @@ +"""``python -m solidworks_mcp.doc_links`` (spec: docs/llms-txt, docs/link-check).""" + +from __future__ import annotations + +import runpy +import sys +from pathlib import Path + +import httpx +import pytest + +from solidworks_mcp.doc_links import __main__ as cli +from solidworks_mcp.doc_links.llms_txt import LLMS_TXT + + +def test_build_then_check_pass(site_root: Path) -> None: + assert cli.main(["build", "--root", str(site_root)]) == 0 + assert (site_root / LLMS_TXT).read_text(encoding="utf-8").startswith("# Proj\n") + assert cli.main(["check", "--root", str(site_root)]) == 0 + + +def test_build_fails_on_a_bad_page(site_root: Path) -> None: + (site_root / "docs/index.md").write_text("no heading\n", encoding="utf-8") + + assert cli.main(["build", "--root", str(site_root)]) == 1 + assert not (site_root / LLMS_TXT).exists() + + +def test_check_fails_on_a_broken_link(site_root: Path) -> None: + cli.main(["build", "--root", str(site_root)]) + page = site_root / "docs/guide/more.md" + page.write_text( + page.read_text(encoding="utf-8") + "\n[x](gone.md)\n", encoding="utf-8" + ) + + assert cli.main(["check", "--root", str(site_root)]) == 1 + + +def _patch_transport(monkeypatch: pytest.MonkeyPatch, status: int) -> None: + real = cli.check_external + + async def fake(links, **kwargs): # type: ignore[no-untyped-def] + transport = httpx.MockTransport(lambda r: httpx.Response(status)) + return await real(links, transport=transport, pause=0) + + monkeypatch.setattr(cli, "check_external", fake) + + +@pytest.mark.parametrize(("status", "code"), [(200, 0), (404, 1)]) +def test_check_external_writes_the_report( + site_root: Path, monkeypatch: pytest.MonkeyPatch, status: int, code: int +) -> None: + (site_root / "README.md").write_text("[x](https://a.example/)\n", encoding="utf-8") + _patch_transport(monkeypatch, status) + + assert cli.main(["check-external", "--root", str(site_root)]) == code + text = (site_root / cli.REPORT).read_text(encoding="utf-8") + assert "https://a.example/" in text + + +def test_check_external_logs_where_a_redirect_went( + site_root: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + (site_root / "README.md").write_text("[x](https://a.example/)\n", encoding="utf-8") + + def handler(request: httpx.Request) -> httpx.Response: + if request.url.host == "a.example": + return httpx.Response(302, headers={"Location": "https://b.example/"}) + return httpx.Response(200) + + real = cli.check_external + + async def fake(links, **kwargs): # type: ignore[no-untyped-def] + return await real(links, transport=httpx.MockTransport(handler), pause=0) + + monkeypatch.setattr(cli, "check_external", fake) + + assert cli.main(["check-external", "--root", str(site_root)]) == 1 + + +def test_run_as_a_module(site_root: Path, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(sys, "argv", ["doc_links", "build", "--root", str(site_root)]) + monkeypatch.delitem(sys.modules, "solidworks_mcp.doc_links.__main__", raising=False) + + with pytest.raises(SystemExit) as exit_: + runpy.run_module("solidworks_mcp.doc_links", run_name="__main__") + + assert exit_.value.code == 0 diff --git a/tests/solidworks_mcp/doc_links/test_links.py b/tests/solidworks_mcp/doc_links/test_links.py new file mode 100644 index 00000000..1ccc7190 --- /dev/null +++ b/tests/solidworks_mcp/doc_links/test_links.py @@ -0,0 +1,384 @@ +"""Finding and checking links (spec: docs/link-check).""" + +from __future__ import annotations + +import asyncio +from pathlib import Path + +import httpx +import pytest + +from solidworks_mcp.doc_links.links import ( + Link, + Result, + all_links, + api_probe, + check_external, + check_internal, + checked_files, + find_links, + github_headers, + is_external, + report, + same_site, + visit, +) +from solidworks_mcp.doc_links.pages import load_site + +from .conftest import REPO, SITE + + +def _targets(text: str) -> list[str]: + return [link.target for link in find_links(text, "f.md")] + + +def test_find_links_of_every_kind() -> None: + text = ( + '[a](a.md) and ![img](i.png "title") and [b](<b.md>)\n' + "[![badge](https://img/x.svg)](https://site/y)\n" + "<https://auto.example/p> and https://bare.example/q.\n" + '<a href="h.md">h</a> <img src="s.png">\n' + "[ref]: https://ref.example/r\n" + "[mail](mailto:me@example.com)\n" + ) + + assert _targets(text) == [ + "i.png", + "a.md", + "b.md", + "https://img/x.svg", + "https://site/y", + "https://auto.example/p", + "https://bare.example/q", + "h.md", + "s.png", + "https://ref.example/r", + ] + + +def test_find_links_skips_code() -> None: + text = "```\n[x](in-fence.md) http://127.0.0.1:1\n```\nUse `http://YOUR-IP:8000` [y](y.md)\n" + + links = find_links(text, "f.md") + + assert links == [Link("f.md", 4, "y.md")] + + +def test_checked_files_and_all_links(site_root: Path) -> None: + (site_root / "README.md").write_text("[docs](docs/index.md)\n", encoding="utf-8") + (site_root / "docs/llms.txt").write_text(f"- [P]({SITE}/): x\n", encoding="utf-8") + + files = [p.relative_to(site_root).as_posix() for p in checked_files(site_root)] + links = all_links(site_root) + + assert files == [ + "README.md", + "docs/guide/more.md", + "docs/guide/start.md", + "docs/index.md", + "docs/llms.txt", + ] + assert Link("docs/llms.txt", 1, f"{SITE}/") in links + assert Link("README.md", 1, "docs/index.md") in links + + +@pytest.mark.parametrize( + ("target", "external"), + [("https://x", True), ("mailto:x", True), ("a.md", False), ("#a", False)], +) +def test_is_external(target: str, external: bool) -> None: + assert is_external(target) is external + + +def _problems(root: Path, file: str, *targets: str) -> list[str]: + links = [Link(file, n, t) for n, t in enumerate(targets, start=1)] + return check_internal(root, load_site(root), links) + + +def test_check_internal_passes_good_links(site_root: Path) -> None: + (site_root / "docs/img.png").write_bytes(b"x") + (site_root / "src.py").write_text("", encoding="utf-8") + (site_root / "docs/sub").mkdir() + (site_root / "docs/sub/index.md").write_text("# Sub\n", encoding="utf-8") + (site_root / "docs/empty").mkdir() + + assert ( + _problems( + site_root, + "docs/guide/start.md", + "more.md#details_1", + "#top", + "#details", + "../img.png", + "../sub/", + "../sub/#sub", + "../empty/#x", + "../api/solidworks_mcp/", + "/src.py", + "more.md?plain=1", + "https://other.example/", + f"{SITE}", + f"{SITE}/guide/more/#details", + f"{SITE}/img.png", + f"{SITE}/api/x/", + f"{REPO}/blob/main/src.py", + f"{REPO}/issues/1", + ) + == [] + ) + + +def test_check_internal_reports_missing_files_and_anchors(site_root: Path) -> None: + problems = _problems( + site_root, + "docs/guide/start.md", + "gone.md", + "more.md#nope", + f"{SITE}/guide/gone/", + f"{REPO}/tree/main/nope", + ) + + assert problems == [ + "docs/guide/start.md:1: gone.md: no such file (docs/guide/gone.md)", + "docs/guide/start.md:2: more.md#nope: docs/guide/more.md has no heading or id `nope`", + f"docs/guide/start.md:3: {SITE}/guide/gone/: no such file (docs/guide/gone)", + f"docs/guide/start.md:4: {REPO}/tree/main/nope: no such file (nope)", + ] + + +def test_check_internal_names_a_path_outside_the_root(site_root: Path) -> None: + (problem,) = _problems(site_root, "docs/index.md", "../../outside-nowhere.md") + + assert "no such file" in problem and "outside-nowhere.md" in problem + + +def test_check_internal_resolves_readme_links_from_the_root(site_root: Path) -> None: + assert _problems(site_root, "README.md", "docs/index.md#proj", "docs/") == [] + + +@pytest.mark.parametrize( + ("url", "final", "same"), + [ + ("https://www.a.com/x", "https://a.com/y", True), + ("https://codecov.io/gh", "https://app.codecov.io/gh", True), + ("https://app.b.io/", "https://b.io/", True), + ( + "https://github.com/o/r/releases/download/x", + "https://objects.githubusercontent.com/z", + True, + ), + ("https://andrewbartels1.github.io/p/", "https://andrewbartels1.com/p/", True), + ("https://a.com/", "https://parked.example/", False), + ("https://notcodecov.io/", "https://codecov.io/", False), + ], +) +def test_same_site(url: str, final: str, same: bool) -> None: + assert same_site(url, final) is same + + +def test_api_probe_and_headers() -> None: + assert ( + api_probe(f"{REPO}/issues/12") + == "https://api.github.com/repos/owner/proj/issues/12" + ) + assert ( + api_probe(f"{REPO}/pull/3/") + == "https://api.github.com/repos/owner/proj/issues/3" + ) + assert api_probe(f"{REPO}/blob/main/x") is None + assert github_headers({"GH_TOKEN": "t"}) == {"Authorization": "Bearer t"} + assert github_headers({}) == {} + + +async def _no_wait(_seconds: float) -> None: + return None + + +def _client(handler) -> httpx.AsyncClient: # type: ignore[no-untyped-def] + return httpx.AsyncClient( + transport=httpx.MockTransport(handler), follow_redirects=True + ) + + +def _visit(handler, url: str, **kwargs) -> Result: # type: ignore[no-untyped-def] + async def run() -> Result: + async with _client(handler) as client: + return await visit(client, url, sleep=_no_wait, **kwargs) + + return asyncio.run(run()) + + +def test_visit_passes_a_200() -> None: + result = _visit(lambda r: httpx.Response(200), "https://a.com/") + + assert (result.ok, result.detail, result.final_url) == (True, "HTTP 200", None) + + +def test_visit_fails_a_404_at_once() -> None: + calls: list[str] = [] + + def handler(request: httpx.Request) -> httpx.Response: + calls.append(str(request.url)) + return httpx.Response(404) + + result = _visit(handler, "https://a.com/x") + + assert (result.ok, result.detail, len(calls)) == (False, "HTTP 404", 1) + + +def test_visit_fails_a_host_that_does_not_resolve() -> None: + def handler(request: httpx.Request) -> httpx.Response: + raise httpx.ConnectError("name resolution failed", request=request) + + result = _visit(handler, "https://gone.example/") + + assert not result.ok + assert result.detail == "ConnectError: name resolution failed" + + +def test_visit_retries_a_timeout_then_passes() -> None: + tries = iter([True, False]) + + def handler(request: httpx.Request) -> httpx.Response: + if next(tries): + raise httpx.ReadTimeout("slow", request=request) + return httpx.Response(200) + + assert _visit(handler, "https://a.com/").ok + + +def test_visit_gives_up_after_retries() -> None: + def handler(request: httpx.Request) -> httpx.Response: + raise httpx.ConnectTimeout("slow", request=request) + + result = _visit(handler, "https://a.com/", attempts=2) + + assert (result.ok, result.detail) == (False, "ConnectTimeout (tried 2 times)") + + +def test_visit_honours_retry_after_on_429() -> None: + waits: list[float] = [] + + async def record(seconds: float) -> None: + waits.append(seconds) + + responses = iter( + [httpx.Response(429, headers={"Retry-After": "120"}), httpx.Response(503)] + ) + + async def run() -> Result: + async with _client(lambda r: next(responses)) as client: + return await visit( + client, "https://a.com/", attempts=2, pause=1, sleep=record + ) + + result = asyncio.run(run()) + + assert (result.ok, result.detail) == (False, "HTTP 503 (tried 2 times)") + assert waits == [60.0, 1] + + +def _redirecting(to: str): # type: ignore[no-untyped-def] + def handler(request: httpx.Request) -> httpx.Response: + if request.url.host == "a.com" and request.url.path == "/": + return httpx.Response(301, headers={"Location": to}) + return httpx.Response(200) + + return handler + + +def test_visit_fails_a_redirect_to_another_site() -> None: + result = _visit(_redirecting("https://parked.example/"), "https://a.com/") + + assert (result.ok, result.detail, result.final_url) == ( + False, + "redirects to another site", + "https://parked.example/", + ) + + +def test_visit_passes_a_same_site_redirect_and_shows_it() -> None: + result = _visit(_redirecting("https://a.com/en/"), "https://a.com/") + + assert (result.ok, result.final_url) == (True, "https://a.com/en/") + + +def test_visit_uses_the_probe_and_its_headers() -> None: + seen: list[httpx.Request] = [] + + def handler(request: httpx.Request) -> httpx.Response: + seen.append(request) + return httpx.Response(410) + + result = _visit( + handler, + f"{REPO}/issues/1", + probe="https://api.github.com/repos/owner/proj/issues/1", + headers={"Authorization": "Bearer t"}, + ) + + assert (result.ok, result.detail) == (False, "HTTP 410 (GitHub API)") + assert seen[0].url.host == "api.github.com" + assert seen[0].headers["Authorization"] == "Bearer t" + + +def test_check_external_visits_each_url_once(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("GITHUB_TOKEN", "tok") + seen: list[str] = [] + + def handler(request: httpx.Request) -> httpx.Response: + seen.append(str(request.url)) + if request.url.host == "api.github.com": + assert request.headers["Authorization"] == "Bearer tok" + else: + assert "Authorization" not in request.headers + return httpx.Response(200) + + links = [ + Link("a.md", 1, "https://a.com/"), + Link("b.md", 2, "https://a.com/"), + Link("a.md", 3, "relative.md"), + Link("a.md", 4, "https://towardsdatascience.com/article/"), + Link("a.md", 5, f"{REPO}/issues/7"), + ] + + results = asyncio.run( + check_external(links, transport=httpx.MockTransport(handler), pause=0) + ) + + assert sorted(seen) == [ + "https://a.com/", + "https://api.github.com/repos/owner/proj/issues/7", + ] + by_url = {r.url: r for r in results} + assert by_url["https://a.com/"].where == ["a.md:1", "b.md:2"] + assert by_url["https://towardsdatascience.com/article/"].detail.startswith( + "not checked: " + ) + assert by_url[f"{REPO}/issues/7"].detail == "HTTP 200 (GitHub API)" + + +def test_report_lists_every_url_failures_first() -> None: + results = [ + Result("https://ok.example/", True, "HTTP 200", None, ["a.md:1"]), + Result("https://bad.example/", False, "HTTP 404", None, ["b.md:2", "c.md:3"]), + Result( + "https://moved.example/", + True, + "HTTP 200", + "https://moved.example/en/", + ["d.md:4"], + ), + ] + + text = report(results) + + assert "3 external URLs visited: 2 passed, 1 failed." in text + rows = [ + line for line in text.splitlines() if line.startswith("| ") and "://" in line + ] + assert ( + rows[0] == "| **FAIL**: HTTP 404 | https://bad.example/ | | b.md:2, c.md:3 |" + ) + assert rows[1].endswith("| https://moved.example/en/ | d.md:4 |") + assert len(rows) == 3 diff --git a/tests/solidworks_mcp/doc_links/test_llms_txt.py b/tests/solidworks_mcp/doc_links/test_llms_txt.py new file mode 100644 index 00000000..639a2803 --- /dev/null +++ b/tests/solidworks_mcp/doc_links/test_llms_txt.py @@ -0,0 +1,167 @@ +"""Building and checking llms.txt (spec: docs/llms-txt).""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from solidworks_mcp.doc_links.llms_txt import ( + BUILD_COMMAND, + LLMS_TXT, + Entry, + build, + check, + entries, + line_problems, +) +from solidworks_mcp.doc_links.pages import DocsError, load_site + +from .conftest import MKDOCS, PAGES, SITE, write_site + +EXPECTED = f"""\ +# Proj + +> A test project + +## Overview + +- [Proj]({SITE}/): Proj does a thing. See the guide. + +## Guide + +- [Start here]({SITE}/guide/start/): Start with `uv`, then read more. +- [More]({SITE}/guide/more/): More words. +""" + + +def test_build(site_root: Path) -> None: + assert build(site_root) == EXPECTED + + +def test_entries_carry_their_page(site_root: Path) -> None: + first = entries(site_root)[0] + + assert first == Entry("Overview", "index.md", "Proj", f"{SITE}/", first.summary) + assert first.line.startswith(f"- [Proj]({SITE}/): ") + + +def test_build_refuses_a_page_with_hidden_text(tmp_path: Path) -> None: + write_site(tmp_path, {**PAGES, "index.md": "# Proj\n\nHi​there.\n"}) + + with pytest.raises(DocsError, match=r"index.md: hidden character U\+200B"): + build(tmp_path) + + +def test_build_refuses_an_outside_link_left_as_text(tmp_path: Path) -> None: + write_site( + tmp_path, {**PAGES, "index.md": "# Proj\n\nSee <https://evil.example>.\n"} + ) + + with pytest.raises(DocsError, match="link outside this project: https://evil"): + build(tmp_path) + + +def test_build_refuses_bad_site_settings(site_root: Path) -> None: + (site_root / "mkdocs.yml").write_text( + MKDOCS.replace("A test project", "A <b>bold</b> project"), encoding="utf-8" + ) + + with pytest.raises(DocsError, match="mkdocs.yml: HTML tag"): + build(site_root) + + +@pytest.mark.parametrize( + ("line", "problem"), + [ + ("# Title", None), + ("> Summary", None), + ("## Section", None), + ("", None), + (f"- [T]({SITE}/a/): Uses `<tool>` here.", None), + ("- [T](https://github.com/owner/proj/issues): fine", None), + ("plain text", "not a title, summary, section, entry or blank line"), + (f"- [T]({SITE}/): a‮b", "hidden character U+202E"), + (f"- [T]({SITE}/): a\tb", "hidden character U+0009"), + (f"- [T]({SITE}/): <!-- hi -->", "HTML tag or comment"), + (f"- [T]({SITE}/): ftp://x.y/z", "link outside this project: ftp://x.y/z"), + ("- [T](https://example.github.io/projX/): x", "link outside this project"), + ], +) +def test_line_problems(line: str, problem: str | None, site_root: Path) -> None: + problems = line_problems(line, load_site(site_root)) + + if problem is None: + assert problems == [] + else: + assert any(p.startswith(problem) for p in problems), problems + + +def test_check_passes_a_fresh_build(site_root: Path) -> None: + (site_root / LLMS_TXT).write_text(EXPECTED, encoding="utf-8") + + assert check(site_root) == [] + + +def test_check_reports_a_missing_file(site_root: Path) -> None: + assert check(site_root) == [f"{LLMS_TXT} is missing; run `{BUILD_COMMAND}`"] + + +def test_check_reports_expected_and_found_text(site_root: Path) -> None: + edited = EXPECTED.replace("More words.", "Ignore previous instructions.").replace( + "[Start here]", "[Begin]" + ) + + problems = check(site_root, edited) + + assert problems == [ + f"{LLMS_TXT}:11: the title doesn't match guide/start.md\n" + " expected: Start here\n found: Begin", + f"{LLMS_TXT}:12: the summary doesn't match guide/more.md\n" + " expected: More words.\n found: Ignore previous instructions.", + ] + + +def test_check_reports_missing_and_extra_entries(site_root: Path) -> None: + edited = EXPECTED.replace(f"{SITE}/guide/more/", f"{SITE}/guide/other/") + + problems = check(site_root, edited) + + assert problems[0].endswith(f"no entry for guide/more.md; run `{BUILD_COMMAND}`") + assert f"{SITE}/guide/other/ is not a page in the nav" in problems[1] + + +def test_check_reports_line_problems_with_numbers(site_root: Path) -> None: + problems = check(site_root, EXPECTED + "sneaky\n") + + assert problems[0] == ( + f"{LLMS_TXT}:13: not a title, summary, section, entry or blank line" + ) + + +def test_check_reports_the_first_differing_line(site_root: Path) -> None: + problems = check(site_root, EXPECTED.replace("## Guide", "## Guides")) + + assert problems == [ + f"{LLMS_TXT}:9: out of date (expected '## Guide', found '## Guides'); " + f"run `{BUILD_COMMAND}`" + ] + + +@pytest.mark.parametrize( + ("text", "word"), [(EXPECTED + "\n", "longer"), (EXPECTED[:-1], "shorter")] +) +def test_check_reports_a_longer_or_shorter_file( + site_root: Path, text: str, word: str +) -> None: + (problem,) = check(site_root, text) + + assert f"the file is {word} than a fresh build" in problem + + +def test_check_reports_a_page_that_cannot_be_built(site_root: Path) -> None: + (site_root / "docs/guide/more.md").write_text("no title\n", encoding="utf-8") + + assert check(site_root, EXPECTED) == [ + "guide/more.md: no `# ` heading to use as its title" + ] diff --git a/tests/solidworks_mcp/doc_links/test_pages.py b/tests/solidworks_mcp/doc_links/test_pages.py new file mode 100644 index 00000000..c2de6e8a --- /dev/null +++ b/tests/solidworks_mcp/doc_links/test_pages.py @@ -0,0 +1,155 @@ +"""Reading the docs: nav, page openings and heading ids (spec: docs/llms-txt).""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from solidworks_mcp.doc_links.pages import ( + OVERVIEW, + DocsError, + NavPage, + heading_ids, + heading_text, + load_site, + nav_pages, + opening, + page_url, + slugify, + source_lines, +) + +from .conftest import REPO, SITE + +_ROOT = Path(__file__).resolve().parents[3] + + +def test_load_site_reads_settings_and_ignores_python_tags(site_root: Path) -> None: + site = load_site(site_root) + + assert (site.name, site.description) == ("Proj", "A test project") + assert (site.url, site.repo_url) == (SITE, REPO) + assert site.nav[0] == {"Home": "index.md"} + + +def test_nav_pages_in_order_without_api_or_missing(site_root: Path) -> None: + pages = nav_pages(load_site(site_root).nav, site_root / "docs") + + assert pages == [ + NavPage(OVERVIEW, "index.md"), + NavPage("Guide", "guide/start.md"), + NavPage("Guide", "guide/more.md"), + ] + + +def test_nav_pages_accepts_untitled_entries(tmp_path: Path) -> None: + (tmp_path / "a.md").write_text("# A\n", encoding="utf-8") + + assert nav_pages(["a.md", {"S": ["a.md"]}], tmp_path) == [ + NavPage(OVERVIEW, "a.md"), + NavPage("S", "a.md"), + ] + + +@pytest.mark.parametrize( + ("path", "url"), + [ + ("index.md", f"{SITE}/"), + ("guide/start.md", f"{SITE}/guide/start/"), + ("guide/index.md", f"{SITE}/guide/"), + ], +) +def test_page_url(path: str, url: str) -> None: + assert page_url(SITE, path) == url + + +def test_source_lines_marks_code_and_blanks_front_matter() -> None: + text = "---\na: 1\n---\n# T\n```py\nx\n```\nafter\n~~~\n```\n~~~\n" + + lines = source_lines(text) + + assert lines[0] == (1, "", False) + assert [code for _n, _l, code in lines[4:8]] == [True, True, True, False] + assert all(code for _n, _l, code in lines[8:11]) + + +def test_opening_takes_title_and_first_prose_paragraph() -> None: + text = ( + "# Start here {#top}\n\n> A note.\n\n!!! tip\n hi\n\n- a list\n\n" + "| t |\n\n![img](x.png)\n\n[![badge](b.svg)](u)\n\n<div>x</div>\n\n" + '=== "Tab"\n\n indented code\n\n```\ncode\n```\n' + "Use `[not](a link)` and [uv](https://x.y), ![alt](i.png),\n" + "[ref][r] or <https://a.b>.\n\n## Next\n" + ) + + start = opening(text, "p.md") + + assert start.title == "Start here" + assert start.summary == ("Use `[not](a link)` and uv, alt, ref or https://a.b.") + + +def test_opening_paragraph_at_end_of_file() -> None: + assert opening("# T\n\nLast words", "p.md").summary == "Last words" + + +def test_opening_without_title_raises() -> None: + with pytest.raises(DocsError, match="p.md: no `# ` heading"): + opening("Just text\n", "p.md") + + +def test_opening_without_paragraph_raises() -> None: + with pytest.raises(DocsError, match="p.md: no opening paragraph"): + opening("# T\n\n- only a list\n\n## Next\n\nlater\n", "p.md") + + +def test_heading_text_drops_markup() -> None: + assert heading_text("The **`save_file`** [tool](x) <b>now</b>") == ( + "The save_file tool now" + ) + + +@pytest.mark.parametrize( + ("value", "slug"), + [ + ("Tool names", "tool-names"), + ("1. Implemented Tools", "1-implemented-tools"), + ("Missing Medium/Low Priority", "missing-mediumlow-priority"), + ("Café — déjà vu", "cafe-deja-vu"), + ], +) +def test_slugify(value: str, slug: str) -> None: + assert slugify(value) == slug + + +def test_heading_ids_repeats_explicit_and_attribute_ids() -> None: + text = ( + "# Title\n\n## Details\n\n## Details\n\n## Other {#mine .cls}\n\n" + '## Plain {.cls}\n\nPara\n{: #para-id }\n\n<a id="html-id"></a>\n\n' + "```\n## Not a heading\n```\n" + ) + + assert heading_ids(text) == { + "title", + "details", + "details_1", + "mine", + "plain", + "para-id", + "html-id", + } + + +def test_slugify_matches_python_markdown_on_every_docs_heading() -> None: + toc = pytest.importorskip("markdown.extensions.toc") + import re + + checked = 0 + for page in sorted((_ROOT / "docs").rglob("*.md")): + for _n, line, code in source_lines(page.read_text(encoding="utf-8")): + heading = None if code else re.match(r"^#{1,6}\s+(.*?)\s*$", line) + if heading and "{" not in heading.group(1): + text = heading_text(heading.group(1)) + assert slugify(text) == toc.slugify(text, "-"), (page, text) + checked += 1 + assert checked > 100 From b09858e93485a4c2ea3100c9e70e37575cad8127 Mon Sep 17 00:00:00 2001 From: Andrew Bartels <andrewbartels1@gmail.com> Date: Sun, 15 Nov 2026 20:07:52 -0800 Subject: [PATCH 4/4] fix(docs): read mkdocs.yml with yaml.safe_load (Bandit B506) The !!python/name tags are replaced by null before parsing, so the file goes through safe_load and no custom loader is needed. --- src/solidworks_mcp/doc_links/pages.py | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/src/solidworks_mcp/doc_links/pages.py b/src/solidworks_mcp/doc_links/pages.py index e7691f85..f6b7355e 100644 --- a/src/solidworks_mcp/doc_links/pages.py +++ b/src/solidworks_mcp/doc_links/pages.py @@ -25,21 +25,11 @@ class DocsError(Exception): """A page can't give what ``llms.txt`` needs from it (names the page).""" -class _MkDocsLoader(yaml.SafeLoader): - """A safe loader that reads ``!!python/...`` tags as ``None``. - - ``mkdocs.yml`` names Python callables for some Markdown extensions; - only the site settings and the nav are needed here, so those tags are - read as nothing instead of importing anything. - """ - - -def _ignore_tag(loader: yaml.SafeLoader, suffix: str, node: yaml.Node) -> None: - """Read a tagged node as ``None``.""" - return None - - -_MkDocsLoader.add_multi_constructor("tag:yaml.org,2002:python/", _ignore_tag) +#: ``!!python/name:...`` tags in ``mkdocs.yml`` (Markdown extension +#: callables). Only the site settings and the nav are needed here, so each tag +#: is read as ``null`` and the file goes through ``yaml.safe_load``: nothing +#: is ever imported or built from it. +_PYTHON_TAG = re.compile(r"!!python/\S+") @dataclass(frozen=True) @@ -71,7 +61,7 @@ def load_site(root: Path) -> Site: The site settings and nav. """ text = (root / "mkdocs.yml").read_text(encoding="utf-8") - config = yaml.load(text, Loader=_MkDocsLoader) # noqa: S506 - a SafeLoader subclass + config = yaml.safe_load(_PYTHON_TAG.sub("null", text)) return Site( name=config["site_name"], description=config["site_description"],