diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 301f694c..6fb60c43 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,14 +1,14 @@ # Why this file exists, and what it was found by. # # Every other repository in the organisation had one; this one did not. The -# consequence was not theoretical: the abap2UI5-linter moved from 0.1.1 to +# consequence was not theoretical: the abap2UI5 linter moved from 0.1.1 to # 0.2.0 and every consumer was bumped except this one - and it was missed # precisely BECAUSE there was no Dependabot here to open the PR that would # have said so. A gap in the mechanism that notices gaps hides itself. # # Two ecosystems, matching the rest of the organisation: # -# npm vitepress, abaplint and the abap2UI5-linter. The linter is +# npm vitepress, abaplint and the abap2UI5 linter. The linter is # what checks every fenced ABAP block on this site, so a new # rule reaching it decides documentation examples - the one # place a wrong example is copied by everyone who reads it. diff --git a/.gitignore b/.gitignore index 401a00a9..21aeff42 100644 --- a/.gitignore +++ b/.gitignore @@ -13,5 +13,3 @@ docs/.vitepress/dist docs/public/llms.txt docs/public/llms-full.txt docs/public/**/*.md -# ...except the one that was there first: a hand-written page, not a projection -!docs/public/media/diagram.md diff --git a/AGENTS.md b/AGENTS.md index 8f2b0b68..2377733b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,18 @@ person reads the page. Do not put "as an AI, …" prose back into `docs/`. npm run check # test + check:version + docs:build + check:examples + check:samples + check:counts ``` +A documentation repository has no compiler for its prose, but six things in it +are decidable, and all six are decided before a merge: + +| | | +|---|---| +| `test` | the sample-catalogue parser in `scripts/lib/`, against a row of every shape the three sample repositories generate | +| `check:version` | the release number in the nav bar, the deprecations page and the changelog, against the newest release tag of the framework — this one goes stale without anybody touching this repository | +| `docs:build` | a page that does not build is a page nobody can read | +| `check:examples` | the ABAP in the fenced blocks, against the real framework: does it compile, and does the view it builds name controls and properties that exist on the UI5 floor this documentation targets | +| `check:samples` | the **Working Samples** blocks, against [abap2UI5/samples](https://github.com/abap2UI5/samples) | +| `check:counts` | the four figures on `resources/samples.md` — one count per sample repository and the total they add up to — against the catalogues themselves | + `.github/workflows/check.yml` runs the same six, in the same order. Keep the two in step: a step that exists only in `package.json` is a step no pull request has to pass, which is how `npm test` — the pin added *because* the @@ -43,13 +55,33 @@ CI sparse-checks out `SAMPLES.md` from `samples-controls` and `samples-stack` so the page is fully checked; both are `continue-on-error`, because an unreachable repository must cost a figure and not the run. +## What the site publishes for machines + +`docs:build` runs `scripts/generate-llms.mjs` first, which writes three things +into `docs/public/` — generated on every build and **gitignored**, because they +are a projection of the pages next to them: + +| | | +|---|---| +| [`/docs/llms.txt`](https://abap2ui5.github.io/docs/llms.txt) | the map: every page with its title and one line of what it covers, plus the repositories around it | +| [`/docs/llms-full.txt`](https://abap2ui5.github.io/docs/llms-full.txt) | the whole documentation as one markdown document | +| `/docs/.md` | each page as raw markdown, next to its `.html` | + +This is for the reader nothing else reaches: an agent that is simply *asked* +about abap2UI5, with no MCP server and no checkout. Without it, it falls back +on training data — where abap2UI5 still looks like `z2ui5_cl_xml_view`. + +Nothing needs maintaining. Adding a page to the sidebar adds it here. + ## Things that will trip you up -- **The nav bar and the sidebar contain byte-identical lines.** +- **The nav bar and the sidebar contain the same two entries.** `Contribution` and `Sponsor` appear in both `themeConfig.nav` and - `themeConfig.sidebar` in `config.mjs`. A replace-first edit hits the wrong - one and looks like it worked. Verify by reading the built config, not by - grepping the source. + `themeConfig.sidebar` in `config.mjs`. The four lines now carry a `// nav` or + `// sidebar` marker so each one is unique — match on the marker, not on the + link. Any further line that has to exist twice gets the same treatment; + a replace-first edit on a text that appears twice hits the wrong one and + looks like it worked. - **A fenced ABAP example is code, and it is checked.** `check:examples` compiles it and lints the view. It also refuses `z2ui5_cl_xml_view=>` — the frozen builder — unless the page carries the migration banner, and refuses a diff --git a/LICENSE b/LICENSE index a1e3c40b..307ee9dd 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 abap2UI5 +Copyright (c) 2023 - present abap2UI5 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index dfe2083f..aa186d82 100644 --- a/README.md +++ b/README.md @@ -20,40 +20,29 @@ npm run check # what CI runs, all six steps ### What CI checks -A documentation repository has no compiler for its prose, but six things in -it are decidable, and all six are decided before a merge — `npm run check` -and `.github/workflows/check.yml` run the same list, in the same order: - -| | | -|---|---| -| `test` | the sample-catalogue parser in `scripts/lib/`, against a row of every shape the three sample repositories generate | -| `check:version` | the release number in the nav bar, the deprecations page and the changelog, against the newest release tag of the framework — this one goes stale without anybody touching this repository | -| `docs:build` | a page that does not build is a page nobody can read | -| `check:examples` | the ABAP in the fenced blocks, against the real framework: does it compile, and does the view it builds name controls and properties that exist on the UI5 floor this documentation targets | -| `check:samples` | the **Working Samples** blocks, against [abap2UI5/samples](https://github.com/abap2UI5/samples) | -| `check:counts` | the four figures on `resources/samples.md` — one count per sample repository and the total they add up to — against the catalogues themselves | +A documentation repository has no compiler for its prose, but six things in it +are decidable, and `npm run check` decides all six before a merge — the prose +builds (`docs:build`), the fenced ABAP examples compile and the views they +build name real UI5 API (`check:examples`), the sample links and the sample +counts still match the sample repositories (`check:samples`, `check:counts`), +the release number in the nav bar still matches the framework +(`check:version`), and the catalogue parser still parses (`test`). +`.github/workflows/check.yml` runs the same list in the same order, so a green +`npm run check` locally is a green pull request. + +**[AGENTS.md](AGENTS.md) describes each of the six**, what a failure means and +which of them need a sibling checkout to say anything at all — read it before +changing anything beyond prose. ### What the site publishes for machines -`docs:build` runs `scripts/generate-llms.mjs` first, which writes three things -into `docs/public/` — generated on every build and **gitignored**, because they -are a projection of the pages next to them: - -| | | -|---|---| -| [`/docs/llms.txt`](https://abap2ui5.github.io/docs/llms.txt) | the map: every page with its title and one line of what it covers, plus the repositories around it | -| [`/docs/llms-full.txt`](https://abap2ui5.github.io/docs/llms-full.txt) | the whole documentation as one markdown document | -| `/docs/.md` | each page as raw markdown, next to its `.html` | - -This is for the reader nothing else reaches: an agent that is simply *asked* -about abap2UI5, with no MCP server and no checkout. Without it, it falls back -on training data — where abap2UI5 still looks like `z2ui5_cl_xml_view`. - -The page list comes from the **sidebar**, not from a directory walk, so a -machine meets the documentation in the order a reader does. A page in the tree -that no sidebar links is reported by name and published anyway. - -Nothing needs maintaining. Adding a page to the sidebar adds it here. +Besides the site, `docs:build` writes [`llms.txt`](https://abap2ui5.github.io/docs/llms.txt), +[`llms-full.txt`](https://abap2ui5.github.io/docs/llms-full.txt) and a raw +`.md` next to every `.html`, so an AI assistant asked about abap2UI5 can read +the current documentation instead of guessing from training data. All three are +generated on every build and gitignored — never edit them, and nothing needs +maintaining: the page list comes from the **sidebar**, so adding a page there +adds it here. [AGENTS.md](AGENTS.md) has the details. ### Linking a sample from a page diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index e1c5f577..f60757cd 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -158,8 +158,10 @@ export default defineConfig({ items: [ { text: "Release", link: "/resources/changelog" }, { text: "Support", link: "/resources/support" }, - { text: "Contribution", link: "/resources/contribution" }, - { text: "Sponsor", link: "/resources/sponsor" }, + // NAV copy — the sidebar has the same two entries verbatim, further + // down under "Resource". Search for this marker, not for the text. + { text: "Contribution", link: "/resources/contribution" }, // nav + { text: "Sponsor", link: "/resources/sponsor" }, // nav ], }, ], @@ -356,7 +358,7 @@ export default defineConfig({ text: "Troubleshooting", collapsed: true, items: [ - { text: "Debugging", link: "/configuration/troubleshooting" }, + { text: "Debugging", link: "/configuration/debugging" }, { text: "Common Failures", link: "/cookbook/troubleshooting/common_failures" }, ], }, @@ -467,7 +469,7 @@ export default defineConfig({ // other gate in this section is somebody else's; this one is // the only thing that can read a view that does not exist until // the app runs. - { text: "abap2UI5-linter", link: "/technical/tools/linter" }, + { text: "abap2UI5 linter", link: "/technical/tools/linter" }, { text: "abapGit", link: "/technical/tools/abapgit" }, { text: "ajson", link: "/technical/tools/ajson" }, { text: "S-RTTI", link: "/technical/tools/srtti" }, @@ -485,10 +487,12 @@ export default defineConfig({ collapsed: true, items: [ { text: "Reference", link: "/resources/references" }, - // 615 working apps in three repositories, and until this page the - // only way to find out which one to open was to know all three - // existed. The cookbook links individual samples per chapter; this - // says which CATALOGUE answers which question. + // Several hundred working apps in three repositories, and until this + // page the only way to find out which one to open was to know all + // three existed. The cookbook links individual samples per chapter; + // this says which CATALOGUE answers which question. The figures live + // on the page itself, where check:counts verifies them against the + // catalogues - do not repeat one here, where nothing would. { text: "Sample Catalogues", link: "/resources/samples" }, { text: "Who Uses abap2UI5?", link: "/resources/who_uses" }, { text: "Release", link: "/resources/changelog" }, @@ -496,8 +500,11 @@ export default defineConfig({ { text: "License", link: "/resources/license" }, { text: "Support", link: "/resources/support" }, { text: "Contact", link: "/resources/contact" }, - { text: "Contribution", link: "/resources/contribution" }, - { text: "Sponsor", link: "/resources/sponsor" }, + // SIDEBAR copy — the nav bar has the same two entries verbatim, + // further up under the version number. Search for this marker, not + // for the text. + { text: "Contribution", link: "/resources/contribution" }, // sidebar + { text: "Sponsor", link: "/resources/sponsor" }, // sidebar // The logo, the favicon and the cover image, for anyone writing // about abap2UI5. The page existed and no sidebar linked it, so the // only way in was knowing the URL - which nobody looking for a logo diff --git a/docs/configuration/troubleshooting.md b/docs/configuration/debugging.md similarity index 100% rename from docs/configuration/troubleshooting.md rename to docs/configuration/debugging.md diff --git a/docs/cookbook/troubleshooting/common_failures.md b/docs/cookbook/troubleshooting/common_failures.md index bd297204..28950ad7 100644 --- a/docs/cookbook/troubleshooting/common_failures.md +++ b/docs/cookbook/troubleshooting/common_failures.md @@ -8,7 +8,7 @@ samples: Not every problem raises an ABAP exception. Many failures surface only in the browser, fail silently, or look like framework bugs when they are actually pattern mistakes. The sections below cover the ten most common ones — what the symptom looks like and where to find the real cause. ::: tip Developer Tools first -Press `Ctrl+F12` in the running app to open the built-in [Developer Tools](/configuration/troubleshooting) — the **Error**, **Log**, **Previous Request** and **Response** tabs show most of what the browser-DevTools steps below dig for, without leaving the app. +Press `Ctrl+F12` in the running app to open the built-in [Developer Tools](/configuration/debugging) — the **Error**, **Log**, **Previous Request** and **Response** tabs show most of what the browser-DevTools steps below dig for, without leaving the app. ::: ## Binding-Path Mismatch diff --git a/docs/cookbook/view/definition.md b/docs/cookbook/view/definition.md index 2e5fece9..27ff848d 100644 --- a/docs/cookbook/view/definition.md +++ b/docs/cookbook/view/definition.md @@ -106,7 +106,7 @@ Tips for working with views: - The [VS Code extension](https://github.com/abap2UI5/vscode-extension) gives the chain completion and hover for the whole UI5 API, and checks the view while you type. -- The [abap2UI5-linter](https://github.com/abap2UI5/linter) rebuilds the view +- The [abap2UI5 linter](https://github.com/abap2UI5/linter) rebuilds the view from your chain and reports unknown controls, properties, enum values and `@since` violations — no SAP system involved. - See the [samples repository](/get_started/next#sample-apps) for ready-made @@ -131,7 +131,7 @@ control** to confirm: - which parent controls are valid for the control you want to use. The ABAP compiler cannot catch these mistakes — they are pure UI5 concerns. -The [abap2UI5-linter](https://github.com/abap2UI5/linter) catches a large part +The [abap2UI5 linter](https://github.com/abap2UI5/linter) catches a large part of them before you deploy, and the rest have to be verified against the SDK. ::: diff --git a/docs/get_started/ai.md b/docs/get_started/ai.md index c6389d5a..dc574cf4 100644 --- a/docs/get_started/ai.md +++ b/docs/get_started/ai.md @@ -47,7 +47,7 @@ can run them on its own: npm run check ``` -The [abap2UI5-linter](/technical/tools/linter) half is the one that matters +The [abap2UI5 linter](/technical/tools/linter) half is the one that matters here: it reconstructs the view from the builder chain and reports the names UI5 does not have, the bindings that point at nothing — and a class still built on the frozen builder. diff --git a/docs/get_started/next.md b/docs/get_started/next.md index ad29c8c7..31c87117 100644 --- a/docs/get_started/next.md +++ b/docs/get_started/next.md @@ -12,7 +12,9 @@ Looking for one in particular? The [sample catalogue](https://github.com/abap2UI ![Sample apps overview showing tables, lists, trees, and other UI5 controls](/get_started/image-1.png) -_No system at hand? Run the samples directly [in your browser](https://abap2ui5.github.io/web-abap2ui5-samples/)._ +_No system at hand? The [live demo](https://abap2ui5.github.io/web-abap2UI5-build/) runs +these samples in the browser — the whole abap2UI5 stack, backend included, +transpiled to JavaScript and rebuilt daily from `main`. Nothing to install._ ::: tip Contribution The samples evolve all the time. Have one to share? Open a PR so others can learn from it. diff --git a/docs/get_started/project_setup.md b/docs/get_started/project_setup.md index a785d95f..95b18ac7 100644 --- a/docs/get_started/project_setup.md +++ b/docs/get_started/project_setup.md @@ -20,7 +20,7 @@ repository, already assembled. | --- | --- | | `src/zcl_app_001` | a working app — an input, a bound table, an event — in the canonical shape its `AGENTS.md` describes | | `abaplint.jsonc` | ABAP syntax and style, with the framework resolved as a dependency, so it compiles the app **without an SAP system** | -| `abap2ui5lint.jsonc` | the [abap2UI5-linter](/technical/tools/linter) — the view your ABAP builds, judged against the UI5 API and against your own class | +| `abap2ui5lint.jsonc` | the [abap2UI5 linter](/technical/tools/linter) — the view your ABAP builds, judged against the UI5 API and against your own class | | `.github/workflows/check.yml` | both gates on every push and pull request, at the versions `package-lock.json` pins — so CI and your machine run the same thing | | `AGENTS.md` | the conventions an AI assistant should follow in this project, plus a `.claude/settings.json` allowlist so it can run the gates without asking | @@ -76,5 +76,5 @@ checks just passed. ## Next Steps - [Tooling](/get_started/tooling) — the editor and agent side of the same loop -- [abap2UI5-linter](/technical/tools/linter) — what the view gate actually +- [abap2UI5 linter](/technical/tools/linter) — what the view gate actually checks, and how to adopt it on a codebase that already exists diff --git a/docs/get_started/quickstart.md b/docs/get_started/quickstart.md index e91cbcb2..f36e1ebc 100644 --- a/docs/get_started/quickstart.md +++ b/docs/get_started/quickstart.md @@ -3,6 +3,16 @@ outline: [2, 4] --- # Quickstart +::: tip No system at hand? +Try abap2UI5 first in the +[**live demo**](https://abap2ui5.github.io/web-abap2UI5-build/): the complete +stack — framework, backend and sample apps — downported, transpiled to +JavaScript and running inside your browser tab, against an in-memory database. +No installation, no SAP system, no login. It is rebuilt daily from `main`, so +what you click there is the current framework. Come back here when you want the +same apps on a real system. +::: + ## 1. Installation via abapGit Install [abap2UI5](https://github.com/abap2UI5/abap2UI5) with [abapGit](https://abapgit.org). (New to abapGit? Install it first — see [abapGit](/technical/tools/abapgit); it's the one-time tool used to pull abap2UI5 into your system.) diff --git a/docs/public/configuration/troubleshooting.html b/docs/public/configuration/troubleshooting.html new file mode 100644 index 00000000..646c9bd8 --- /dev/null +++ b/docs/public/configuration/troubleshooting.html @@ -0,0 +1,29 @@ + + + + + + Page moved - abap2UI5 + + + + + +

+ This page moved to + Debugging. +

+ + diff --git "a/docs/public/media/Pra\314\210sentation1.key" "b/docs/public/media/Pra\314\210sentation1.key" deleted file mode 100644 index dae23387..00000000 Binary files "a/docs/public/media/Pra\314\210sentation1.key" and /dev/null differ diff --git a/docs/public/media/diagram.md b/docs/public/media/diagram.md deleted file mode 100644 index 0c531b86..00000000 --- a/docs/public/media/diagram.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -outline: [2, 4] ---- -# Diagrams - -template: https://excalidraw.com/#json=0RTUTjZIETtW3xH1BiMzu,9qHMUMJWWWCcVvwNP1cssA - -https://excalidraw.com/#json=BJn48sFEiUhkxqmqcR7eU,6XG1ICReulkK2-28Afva5Q - -BLOGS - -BLOGS -https://excalidraw.com/#json=gGHN4CzX4V4hJ6rg6rYL1,rsa1mKFrqbqQaHrBbV0k-g diff --git a/docs/public/media/diagram_old.key b/docs/public/media/diagram_old.key deleted file mode 100644 index 2ff139db..00000000 Binary files a/docs/public/media/diagram_old.key and /dev/null differ diff --git a/docs/public/media/logo.pptx b/docs/public/media/logo.pptx deleted file mode 100644 index a412f03f..00000000 Binary files a/docs/public/media/logo.pptx and /dev/null differ diff --git a/docs/public/media/logo/logo_pp.key b/docs/public/media/logo/logo_pp.key deleted file mode 100644 index 6d24398e..00000000 Binary files a/docs/public/media/logo/logo_pp.key and /dev/null differ diff --git a/docs/resources/deprecations.md b/docs/resources/deprecations.md index c34f1c00..cbf16618 100644 --- a/docs/resources/deprecations.md +++ b/docs/resources/deprecations.md @@ -15,7 +15,7 @@ UI5 itself (`sap.ui.commons`, the legacy charts, the Belize themes …) see ## Start with the linter Most of this page can be found — and part of it fixed — without reading -further. The [abap2UI5-linter](https://github.com/abap2UI5/linter) checks app +further. The [abap2UI5 linter](https://github.com/abap2UI5/linter) checks app classes without an SAP system and rewrites the mechanical corrections in place: ```sh diff --git a/docs/resources/sponsor.md b/docs/resources/sponsor.md index b3322e7c..b543a2df 100644 --- a/docs/resources/sponsor.md +++ b/docs/resources/sponsor.md @@ -20,8 +20,8 @@ Other open-source projects extend abap2UI5. Please consider sponsoring their mai - ABAP Cloud and Standard compatibility with [Steampunkification](https://github.com/heliconialabs/steampunkification) [(contributors)](https://github.com/heliconialabs/steampunkification/graphs/contributors) - Syntax downporting via the [downport repositories](https://github.com/abap2UI5-downports) by [abaplint](https://abaplint.org/) [(larshp)](https://github.com/larshp) - Namespace renaming with [abaplint](https://abaplint.org/) [(larshp)](https://github.com/larshp) -- Browser testing with [Playwright](https://playwright.dev/) and [abap2UI5-web](https://github.com/abap2UI5/abap2UI5-web) [(larshp)](https://github.com/larshp) -- Live demos via [web-abap2ui5-samples](https://github.com/abap2UI5/web-abap2ui5-samples) [(larshp)](https://github.com/larshp) +- Browser testing with [Playwright](https://playwright.dev/) and [web-abap2UI5](https://github.com/abap2UI5/web-abap2UI5) [(larshp)](https://github.com/larshp) +- Live demos via [web-abap2UI5-build](https://abap2ui5.github.io/web-abap2UI5-build/) [(larshp)](https://github.com/larshp) - Code cleanup with [ABAP Cleaner](https://github.com/SAP/abap-cleaner) [(contributors)](https://github.com/SAP/abap-cleaner/graphs/contributors) - Documentation built with [VitePress](https://vitepress.dev/) [(contributors)](https://github.com/vuejs/vitepress/graphs/contributors) diff --git a/docs/technical/tools/linter.md b/docs/technical/tools/linter.md index 0c48573b..953f5e90 100644 --- a/docs/technical/tools/linter.md +++ b/docs/technical/tools/linter.md @@ -1,7 +1,7 @@ --- outline: [2, 4] --- -# abap2UI5-linter +# abap2UI5 linter The view an abap2UI5 app shows does not exist until the app runs. It is built by a chain of `z2ui5_cl_ui5_view_builder` calls and handed to the browser as a @@ -12,12 +12,17 @@ reconstructs the view from the builder chain and judges the class and the view **together**. ```sh -npx abap2ui5lint src +npx @abap2ui5/linter src ``` No SAP system, no install, no configuration. The package is small and pulls in nothing else, so that line is a fast one. +Name the **package** there, not the command: the executable it installs is +called `abap2ui5lint` — and so are the config file, the baseline and the +in-source waivers below — but `npx abap2ui5lint` would go looking for a package +of that name, which is not this one. + ## What it checks Two gates. @@ -63,7 +68,7 @@ anchor of its page in the rule reference at Some rules carry an exact correction and are rewritten in place: ```sh -abap2ui5lint src --fix # or --fix-dry-run to see it first +npx @abap2ui5/linter src --fix # or --fix-dry-run to see it first ``` Only corrections that need no guessing — an obsolete call renamed, a missing @@ -75,7 +80,7 @@ once, which is the moment most adoptions stop. The **baseline** freezes that debt instead of hiding it: ```sh -npx abap2ui5lint src --update-baseline +npx @abap2ui5/linter src --update-baseline ``` Commit the resulting `abap2ui5lint-baseline.json` and name it in the config. diff --git a/scripts/generate-llms.mjs b/scripts/generate-llms.mjs index b5b83204..745d240e 100644 --- a/scripts/generate-llms.mjs +++ b/scripts/generate-llms.mjs @@ -197,6 +197,15 @@ const index = [ '- [llms-full.txt](' + SITE + '/llms-full.txt): the whole documentation as one', ' document, if you would rather fetch it once than page by page', '', + /* The framework repository publishes a file of the same name describing the + * CODE - the src/ layering, the public API, where each concept is + * implemented. Its copy points here for the prose; without this line the + * pairing is only visible from that side, and a reader who arrived at the + * documentation first never learns the other half exists. */ + '- [the code map](https://github.com/abap2UI5/abap2UI5/blob/main/llms.txt): the same', + ' idea for the framework source - the package layering, the public API and', + ' where each concept lives. This file maps the prose, that one maps the code', + '', ...[...bySection].flatMap(([section, list]) => [ `## ${section}`, '',