diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json new file mode 100644 index 00000000..7f363e6f --- /dev/null +++ b/.config/dotnet-tools.json @@ -0,0 +1,13 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "libmentor": { + "version": "0.1.0", + "commands": [ + "libmentor" + ], + "rollForward": false + } + } +} diff --git a/.github/actions/libmentor/action.yml b/.github/actions/libmentor/action.yml new file mode 100644 index 00000000..39b61a02 --- /dev/null +++ b/.github/actions/libmentor/action.yml @@ -0,0 +1,19 @@ +name: Generate LibMentor documentation +description: Build validated AI documentation from a versioned source snapshot +runs: + using: composite + steps: + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x + - name: Restore pinned CLI + shell: bash + working-directory: ${{ github.workspace }} + run: dotnet tool restore + - name: Generate and verify + shell: bash + working-directory: ${{ github.workspace }} + run: | + version="$(python3 .github/scripts/libmentor-version.py)" + dotnet tool run libmentor -- generate --revision "$GITHUB_SHA" --library-version "$version" + dotnet tool run libmentor -- generate --check --revision "$GITHUB_SHA" --library-version "$version" diff --git a/.github/scripts/libmentor-version.py b/.github/scripts/libmentor-version.py new file mode 100644 index 00000000..77c740cb --- /dev/null +++ b/.github/scripts/libmentor-version.py @@ -0,0 +1,11 @@ +import json +import os +from pathlib import Path +import xml.etree.ElementTree as ET + +version = ET.parse("Version.props").findtext(".//PackageVersion") +if not version: + raise SystemExit("Library version could not be resolved.") +revision = os.environ.get("GITHUB_SHA", "local")[:12] +base = version.split("+", 1)[0] +print(base + (".source." if "-" in base else "-source.") + revision) diff --git a/.github/workflows/libmentor.yml b/.github/workflows/libmentor.yml new file mode 100644 index 00000000..27036ad9 --- /dev/null +++ b/.github/workflows/libmentor.yml @@ -0,0 +1,19 @@ +name: LibMentor validation +on: + pull_request: + push: + branches: [main] + workflow_dispatch: +permissions: + contents: read +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: ./.github/actions/libmentor + - uses: actions/upload-artifact@v4 + with: + name: libmentor-documentation + path: .libmentor + include-hidden-files: true diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index f85af7a8..fca74aec 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -12,6 +12,13 @@ on: branches: [main] paths: - 'docs/**' + - 'Nextended.*/**' + - 'Version.props' + - 'README.md' + - 'libmentor.json' + - '.config/dotnet-tools.json' + - '.github/actions/libmentor/**' + - '.github/scripts/libmentor-version.py' - 'icon.png' - '.github/workflows/pages.yml' workflow_dispatch: @@ -52,6 +59,11 @@ jobs: working-directory: docs run: npm run build + - uses: ./.github/actions/libmentor + + - name: Include AI documentation + run: cp -R .libmentor docs/.vitepress/dist/ai + - uses: actions/configure-pages@v5 - uses: actions/upload-pages-artifact@v3 diff --git a/.gitignore b/.gitignore index ac874631..9cc102c0 100644 --- a/.gitignore +++ b/.gitignore @@ -364,3 +364,6 @@ MigrationBackup/ docs/node_modules/ docs/.vitepress/dist/ docs/.vitepress/cache/ + +.libmentor/ +.libmentor-inputs/ diff --git a/LIBMENTOR.md b/LIBMENTOR.md new file mode 100644 index 00000000..fcd33581 --- /dev/null +++ b/LIBMENTOR.md @@ -0,0 +1,11 @@ +# AI documentation + +LibMentor generates versioned documentation from this repository. Restore the pinned tool with `dotnet tool restore`, then run `dotnet tool run libmentor -- generate`. + +CI resolves the library version from its existing metadata and adds a source revision suffix. This describes the source snapshot, rather than claiming that a package with the same version has already been released. Files are generated under `.libmentor/`; repository contributor instructions are preserved. + +The consumer entry point after deployment is [llms.txt](https://fgilde.github.io/Nextended/ai/llms.txt). The same output is available as the `libmentor-documentation` workflow artifact. The first LibMentor 0.1.0 NuGet release must exist before tool restore can succeed. + +The published skill is under `ai/skills/`. Copy the complete library folder, including its references, to your client's skills directory. + +Generation validates local Markdown links and explicit API-symbol links. C# source declarations are parsed without a project build; see extraction evidence in `knowledge.json`. Compiled Razor APIs require compiler XML input. Markdown code fences are not compiled automatically. diff --git a/README.md b/README.md index e0f22692..c3d728c5 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ | **Documentation portal** | [fgilde.github.io/Nextended](https://fgilde.github.io/Nextended/) | [Dokumentationsportal](docs/de/index.md) | | **Getting started** | [Installation](docs/guides/installation.md) | [Installation](docs/de/guides/installation.md) | | **Architecture** | [Overview](docs/guides/architecture.md) | [Überblick](docs/de/guides/architecture.md) | -| **Per-package guides** | [Projects](docs/projects/README.md) | [Projekte](docs/de/projects/README.md) | +| **Per-package guides** | [Projects](docs/projects/index.md) | [Projekte](docs/de/projects/index.md) | | **Examples** | [Common use cases](docs/examples/common-use-cases.md) | [Typische Anwendungsfälle](docs/de/examples/common-use-cases.md) | ## Packages diff --git a/libmentor.json b/libmentor.json new file mode 100644 index 00000000..deac4062 --- /dev/null +++ b/libmentor.json @@ -0,0 +1,33 @@ +{ + "schemaVersion": 1, + "name": "Nextended", + "repository": "https://github.com/fgilde/Nextended", + "revision": "main", + "output": ".libmentor", + "exclude": [ + "**/*.de.md", + "docs/de/**", + "**/node_modules/**" + ], + "examples": [], + "guidance": [ + "This is a source snapshot. Check the installed package version and API evidence before suggesting code." + ], + "description": "Extension packages for .NET, Blazor, EF Core and Aspire.", + "version": "10.1.51-source", + "documents": [ + "README.md", + "Nextended.*/README.md", + "docs/**/*.md" + ], + "sources": [ + "Nextended.*/**/*.cs" + ], + "packages": [ + "Nextended.Core", + "Nextended.Blazor", + "Nextended.EF", + "Nextended.Aspire" + ], + "baseUrl": "https://fgilde.github.io/Nextended/ai" +}