Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
868e4e1d99 | ||
|
|
8b879fcb4a | ||
|
|
2374115337 |
No files matched your search
@@ -0,0 +1,100 @@
|
||||
# The GitHub Wiki is a copy of the repository's own pages (D53/D54, the owner, 2026-10-07): wiki/ (Home, the sidebar,
|
||||
# the developer pages) and guide/ (the user guide, which is the End-user part) with LIMITATIONS.md, assembled and checked
|
||||
# by tools/wiki-build.ps1 - the check build.ps1 runs as `wiki-check`. A page edited on the Wiki tab is overwritten here;
|
||||
# edit wiki/ or guide/ instead (docs/13_CI_CD.md §wiki.yml).
|
||||
#
|
||||
# Separate from release.yml on purpose. The release stays as it was and its dry run stays a pure rehearsal; a wiki that
|
||||
# fails to publish is a red run of its own, re-run on its own, never a red release. A step after `gh release create`
|
||||
# could never be re-run at all: the release would already exist.
|
||||
#
|
||||
# A release that release.yml creates with GITHUB_TOKEN fires no `release` event for other workflows. `workflow_run` does
|
||||
# fire - the Release run itself was started by the owner's tag push - and it runs THIS file as it is on main, so the job
|
||||
# checks out the commit the release was built from (head_sha) and links the repository's files at the tag (head_branch).
|
||||
|
||||
name: Wiki
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [Release]
|
||||
types: [completed]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
ref:
|
||||
description: 'Branch, tag or commit to build the wiki from; repository files are linked at this ref'
|
||||
required: true
|
||||
default: main
|
||||
type: string
|
||||
publish:
|
||||
description: 'Publish to the Wiki tab (off: build, check and upload the pages only)'
|
||||
required: true
|
||||
default: false
|
||||
type: boolean
|
||||
|
||||
# The repository's default token is read-only; pushing to <repo>.wiki.git needs contents: write.
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
group: wiki
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
wiki:
|
||||
# A rehearsal of release.yml (workflow_dispatch) never publishes the wiki: only a run started by a pushed v* tag
|
||||
# that succeeded.
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
(github.event.workflow_run.conclusion == 'success' &&
|
||||
github.event.workflow_run.event == 'push' &&
|
||||
startsWith(github.event.workflow_run.head_branch, 'v'))
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 10
|
||||
env:
|
||||
# Values reach the scripts through the environment only, never pasted into them.
|
||||
WIKI_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_branch }}
|
||||
WIKI_PUBLISH: ${{ github.event_name == 'workflow_run' || inputs.publish }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_sha }}
|
||||
persist-credentials: false
|
||||
|
||||
- name: Build and check the wiki
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
./tools/wiki-build.ps1 -Ref $env:WIKI_REF -Out out/wiki
|
||||
if ($LASTEXITCODE -ne 0) { throw 'wiki-build failed' }
|
||||
|
||||
- name: Upload the pages
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: wiki-${{ github.run_id }}
|
||||
path: out/wiki/**
|
||||
if-no-files-found: error
|
||||
retention-days: 14
|
||||
|
||||
- name: Publish to the Wiki tab
|
||||
if: env.WIKI_PUBLISH == 'true'
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
gh auth setup-git
|
||||
if ($LASTEXITCODE -ne 0) { throw 'gh auth setup-git failed' }
|
||||
git clone --depth 1 "https://github.com/$env:GITHUB_REPOSITORY.wiki.git" wiki-repo
|
||||
if ($LASTEXITCODE -ne 0) { throw 'cloning the wiki failed - it must have one page created on github.com first' }
|
||||
Get-ChildItem wiki-repo -Force | Where-Object Name -ne '.git' | Remove-Item -Recurse -Force
|
||||
Copy-Item out/wiki/* wiki-repo -Recurse
|
||||
Set-Location wiki-repo
|
||||
git add -A
|
||||
git diff --cached --quiet
|
||||
if ($LASTEXITCODE -eq 0) { Write-Host "The wiki already shows $env:WIKI_REF; nothing to publish."; exit 0 }
|
||||
git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' commit -q -m "wiki: $env:WIKI_REF"
|
||||
if ($LASTEXITCODE -ne 0) { throw 'commit failed' }
|
||||
# The wiki repository's branch is master (git ls-remote, 2026-10-07).
|
||||
git push origin HEAD:master
|
||||
if ($LASTEXITCODE -ne 0) { throw 'push failed' }
|
||||
Write-Host "Published the wiki at $env:WIKI_REF"
|
||||
@@ -48,6 +48,11 @@ numeric core and does not move; the heading is the full version — corrected 20
|
||||
button and shortcut), *Every setting* (what each one does and its default), *When something goes wrong* (what you see,
|
||||
what it means, what to do) and *Words FrameLedger uses*. Tests now fail when a setting or a menu item is added without
|
||||
its line in the guide, or a link names a section that does not exist.
|
||||
- **A wiki.** The project's [wiki](https://github.com/poli0981/frameledger/wiki) has two halves: the user guide, the
|
||||
same pages the app shows, and short pages for developers — the architecture, the repository, building and testing,
|
||||
the rules every change keeps, capture, metrics, data, the app's UI and releasing — each linking to its full document.
|
||||
It is published from the repository whenever a release is made (`wiki.yml`), so it always matches the newest
|
||||
release, and `./build.ps1 check` fails on any link in it that leads nowhere (`13_CI_CD` §wiki.yml).
|
||||
|
||||
## [0.1.0-beta.16] - 2026-10-06
|
||||
|
||||
|
||||
@@ -138,7 +138,8 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
|
||||
# gen-ac-floor, hookinventory-check, license-check, license-gather
|
||||
# (+ license-overrides/), notice-check, package-closure-check,
|
||||
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
|
||||
# versioninfo-check, vklayer-blastradius, fps-impact-runbook
|
||||
# versioninfo-check, vklayer-blastradius, fps-impact-runbook,
|
||||
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate)
|
||||
# (six names added 2026-10-04)
|
||||
# (PowerShell). This line used to name three, one of which
|
||||
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
|
||||
@@ -155,6 +156,9 @@ guide/ # the user guide (beta.12, D44): ~~eight~~ short
|
||||
# App (Help > User guide); README.md is its contents. docs/ is for developers.
|
||||
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
|
||||
# and the guide is the wiki's End-user part)
|
||||
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
|
||||
# publishes them with guide/ and LIMITATIONS.md to the Wiki tab at a release;
|
||||
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
|
||||
docs/ legal/ legal/licenses/
|
||||
```
|
||||
|
||||
|
||||
@@ -27,6 +27,11 @@ That is the whole quality gate, and continuous integration runs the identical sc
|
||||
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
|
||||
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
|
||||
|
||||
Documentation lives in three places: `guide/` for players (shown in the app and on the wiki), `wiki/` for the wiki's own
|
||||
pages, and `docs/` for developers. A change a player would notice updates `guide/`; a change to how the code is put
|
||||
together updates `docs/` — and the `wiki/` page that summarises it, if that page now says something else.
|
||||
`./build.ps1 check` builds the wiki and fails on a link that leads nowhere.
|
||||
|
||||
Never point a build of your own at the data FrameLedger records into (`%LOCALAPPDATA%\FrameLedger`): a newer build
|
||||
migrates the database, and the released one cannot read it back. To look at real data, copy the folder and start
|
||||
`FrameLedger.exe --data-dir <copy>` — a viewer that starts no Agent and changes nothing on the PC (`docs/12_BUILD.md`
|
||||
|
||||
@@ -5,8 +5,10 @@
|
||||
> No telemetry. No accounts. All data stays on your machine.
|
||||
|
||||
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
|
||||
anti-cheat, and look after your data, a page each. What FrameLedger cannot do is on one page:
|
||||
[Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User guide, Help ▸ Limitations).
|
||||
anti-cheat, and look after your data, a page each, then every screen, every setting and what to do when something goes
|
||||
wrong. What FrameLedger cannot do is on one page: [Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User
|
||||
guide, Help ▸ Limitations), and on the project's [wiki](https://github.com/poli0981/frameledger/wiki) with the developer
|
||||
pages.
|
||||
|
||||
<!-- accuracy-block:begin -->
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-10-06.** The software is a beta; its latest
|
||||
@@ -191,6 +193,8 @@ FrameLedger is GPL-3.0-only free software, and you are welcome to build it, chan
|
||||
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reports: [`SECURITY.md`](SECURITY.md).
|
||||
- **Fork or redistribute:** [`FORKING.md`](FORKING.md) — what the GPL asks of anyone who distributes builds, and the names
|
||||
a fork must change so it does not share FrameLedger's update feed, install folder, data, pipe or Vulkan layer.
|
||||
- **Find your way around:** the [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages are short, and each
|
||||
links to the document it summarises ([`wiki/`](wiki/) is their source).
|
||||
- **Read the design:** the developer documentation is in [`docs/`](docs/). Start with [`CLAUDE.md`](CLAUDE.md), then
|
||||
[`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) — which constrains everything else — then
|
||||
[`docs/01_ARCHITECTURE.md`](docs/01_ARCHITECTURE.md).
|
||||
|
||||
@@ -464,6 +464,15 @@ function Invoke-ProjectGates {
|
||||
Invoke-Checked 'notice-check (self-test)' { & $noticeTool -SelfTest }
|
||||
Invoke-Checked 'notice-check' { & $noticeTool -RepoRoot $repo }
|
||||
|
||||
# beta.17 (D53/D54): the GitHub Wiki is built from wiki/, guide/ and LIMITATIONS.md, and wiki.yml publishes it when a
|
||||
# release is made. A link or a section that leads nowhere, a page nothing leads to, a sidebar out of the guide's
|
||||
# order, a path that names nothing or a version written into a page is red here, not on the published wiki.
|
||||
# Self-test first (nine cases, both directions), then the live assembly into a temporary folder.
|
||||
Write-Step 'wiki-check'
|
||||
$wikiTool = Join-Path $repo 'tools/wiki-build.ps1'
|
||||
Invoke-Checked 'wiki-check (self-test)' { & $wikiTool -RepoRoot $repo -SelfTest }
|
||||
Invoke-Checked 'wiki-check' { & $wikiTool -RepoRoot $repo -Check }
|
||||
|
||||
Write-Step 'changelog-check'
|
||||
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
|
||||
if (Test-Path $changelogTool) {
|
||||
|
||||
@@ -298,6 +298,7 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
|
||||
13b. `tools/accuracy-check.ps1 -SelfTest`, then live — the accuracy block is ONE text (`legal/ACCURACY.md`) embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06)
|
||||
13c. **`tools/notice-check.ps1 -SelfTest`, then live** (beta.12, owner decision D45, 2026-10-03) — every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`, tracked or new, minus `src/native/third_party/`) opens with `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (`NOTICE` carries them); the second line may name another holder and year in the same form (a contributor's own file).
|
||||
Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a missing header, and `tools/resx-gen.ps1` generates the accessor with it
|
||||
13d. **`tools/wiki-build.ps1 -SelfTest`, then `-Check`** (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from `wiki/`, `guide/` and `LIMITATIONS.md` into a temporary folder, as `wiki.yml` does at a release (`13_CI_CD` §wiki.yml), and fails on a link to a file, folder or section that does not exist, two sources for one page, a page that neither Home nor the sidebar leads to, a sidebar that lists the guide in another order than `guide/README.md`, a backticked repository path in a `wiki/` page that names nothing, and a version number written into a `wiki/` page (the footer says which release the wiki shows). Nine self-test cases, both directions
|
||||
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
|
||||
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one). The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
|
||||
15. `tools/resx-audit.ps1` — ~~**skipped loudly; it does not exist, and no `.resx` file does either**~~ **built 2026-09-13 (P3 PR-2)**: `-SelfTest` first (11 fixture cases, both directions), then the live pass over every `Strings.resx` family under `src/` — key sets equal across en/vi/ja, `Safety_*` in `ja` marked for review or signed, `Strings.Designer.cs` current with `tools/resx-gen.ps1`. A tree with no family is red (`09_I18N` §Translation workflow)
|
||||
|
||||
+25
-1
@@ -184,6 +184,29 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix. *(Added 2026-10-04: the PR-only removal step fails the job on any removal, a shrunk per-title list or an added trusted signer, whatever the body says — the justification is for the reviewer, and the job stays red.)*
|
||||
- `permissions: contents: read`.
|
||||
|
||||
### `wiki.yml` — after a successful Release run, and by hand · **repo-local, built 2026-10-07 (beta.17, D53/D54)**
|
||||
- **What:** the GitHub Wiki is a copy of the repository's own pages — `wiki/` (Home, the sidebar, the developer pages)
|
||||
and `guide/` (the user guide: the End-user part, the same pages the App shows) with `LIMITATIONS.md`.
|
||||
`tools/wiki-build.ps1` names each page (a guide page after its first heading, `guide/README.md` as *User-guide*,
|
||||
`LIMITATIONS.md` as *Limitations*), rewrites links between pages to page names and every other repository link to
|
||||
its address on GitHub **at the release's tag**, drops each page's first heading (the wiki prints the page name), and
|
||||
writes a footer naming the tag. The same assembly is `build.ps1`'s `wiki-check` gate (`12_BUILD` §Local quality gate,
|
||||
13d), so a dead link is red on the pull request, never on the published wiki.
|
||||
- **When:** `workflow_run` on `Release`, completed — the job runs only when that run succeeded and was started by a
|
||||
pushed `v*` tag, so a `workflow_dispatch` rehearsal of `release.yml` never publishes. It checks out the run's
|
||||
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. By hand:
|
||||
`gh workflow run wiki.yml -f ref=main -f publish=false` builds, checks and uploads the pages as an artifact; with
|
||||
`publish=true` it publishes them.
|
||||
- **Why not a step of `release.yml`:** the release stays as it was, its rehearsal stays a pure rehearsal, and a wiki
|
||||
that fails to publish is a red run of its own that can be re-run — a step after `gh release create` could never be
|
||||
re-run, the release already existing. A release created with `GITHUB_TOKEN` fires no `release` event for other
|
||||
workflows; `workflow_run` fires because the Release run itself was started by a tag push.
|
||||
- **Publishing:** `gh auth setup-git`, a clone of `<repo>.wiki.git`, everything but `.git` replaced, a commit as
|
||||
`github-actions[bot]` only when something changed, `git push origin HEAD:master` (the wiki's branch is `master`). A
|
||||
page edited on the Wiki tab is overwritten at the next release: edit `wiki/` or `guide/`.
|
||||
- `permissions: contents: write` — the repository's default workflow token is read-only (read from the API,
|
||||
2026-10-07), and pushing to the wiki repository needs write.
|
||||
|
||||
## Dependabot (`.github/dependabot.yml`)
|
||||
|
||||
```yaml
|
||||
@@ -215,7 +238,7 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
|
||||
**In the tree — done:**
|
||||
|
||||
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph
|
||||
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph *(and `wiki.yml` since beta.17, repo-local too: five)*
|
||||
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done
|
||||
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly)
|
||||
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
|
||||
@@ -227,4 +250,5 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
- [ ] `Rules / validate` as a required check (§S23-2, after its skip-shim)
|
||||
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
|
||||
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
|
||||
- [ ] Wiki editing restricted to collaborators (Settings ▸ General ▸ Features ▸ Wikis ▸ *Restrict editing to collaborators only*): otherwise anyone with a GitHub account can change a page until the next release overwrites it (§wiki.yml, beta.17)
|
||||
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
|
||||
+5
-2
@@ -7,7 +7,8 @@ This folder is for people who build, change or review FrameLedger. **If you only
|
||||
|
||||
| You want to… | Read |
|
||||
|---|---|
|
||||
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (D1…D46) and the traps that each cost a cycle. It carries no status on purpose |
|
||||
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (~~D1…D46~~ D1 onward — *corrected 2026-10-07: the range grows with every train*) and the traps that each cost a cycle. It carries no status on purpose |
|
||||
| Find your way around first | The [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages (source: [`../wiki/`](../wiki/), beta.17) — a short page per part, each linking here |
|
||||
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
|
||||
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
|
||||
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE) |
|
||||
@@ -76,7 +77,9 @@ are safety items, and something listed there as unresolved should not be built t
|
||||
|
||||
## Beside this folder
|
||||
|
||||
- [`../guide/`](../guide/README.md) — the user guide (players, English).
|
||||
- [`../guide/`](../guide/README.md) — the user guide (players, English); since beta.17 (D54) also the wiki's End-user part.
|
||||
- [`../wiki/`](../wiki/Home.md) — the wiki's own pages: Home, the sidebar, the developer pages (D53). `wiki.yml`
|
||||
publishes them with the guide to the Wiki tab when a release is made; `build.ps1`'s `wiki-check` holds every link.
|
||||
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
|
||||
texts, the trademark note.
|
||||
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
|
||||
|
||||
@@ -0,0 +1,337 @@
|
||||
# SPDX-License-Identifier: GPL-3.0-only
|
||||
# Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
#Requires -Version 7.0
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Builds the GitHub Wiki from the repository - wiki/ (Home, the sidebar, the developer pages), guide/ (the user
|
||||
guide, which is the wiki's End-user part) and LIMITATIONS.md - and refuses a wiki with a link that leads nowhere.
|
||||
|
||||
.DESCRIPTION
|
||||
D53/D54 (the owner, 2026-10-07): the wiki's source lives in the repository and the Wiki tab is a copy of it, written
|
||||
by .github/workflows/wiki.yml when a release is published. The user guide is the End-user part: one source, shown
|
||||
in the App (Help > User guide) and on the wiki.
|
||||
|
||||
Assembling:
|
||||
- wiki/*.md keeps its file name, which GitHub turns into the page's title (Build-and-test.md: "Build and test").
|
||||
- A guide page becomes the page its first heading names (guide/README.md is User-guide, LIMITATIONS.md is
|
||||
Limitations). Every page's first heading is dropped: the wiki prints the page's name above it.
|
||||
- A link to one of those pages becomes the page's name; a link to any other file or folder of the repository
|
||||
becomes its address on GitHub at -Ref, the release being published; anchors are kept.
|
||||
- _Footer.md is written here, naming -Ref and where to edit.
|
||||
|
||||
Refused, each with a line, exit 1:
|
||||
- a link to a file or folder that does not exist, or to a section no heading of its page produces;
|
||||
- two sources that give one page name;
|
||||
- a page that neither Home nor the sidebar leads to;
|
||||
- a sidebar that lists the guide's pages in another order than guide/README.md does;
|
||||
- a path in backticks in a wiki/ page that names nothing in the repository;
|
||||
- a version number written in a wiki/ page (the footer is where the wiki says which release it shows).
|
||||
|
||||
-Check assembles into a temporary folder and only reports. -SelfTest proves every refusal, both ways, on copies.
|
||||
#>
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string]$RepoRoot = (Split-Path $PSScriptRoot -Parent),
|
||||
[string]$Out,
|
||||
[string]$Ref = 'main',
|
||||
[switch]$Check,
|
||||
[switch]$SelfTest
|
||||
)
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
$repoUrl = 'https://github.com/poli0981/frameledger'
|
||||
$special = @{ 'guide/README.md' = 'User-guide'; 'LIMITATIONS.md' = 'Limitations' }
|
||||
$pathPrefixes = @('src/', 'docs/', 'tools/', 'tests/', 'guide/', 'legal/', 'wiki/', 'rules/', '.github/')
|
||||
$rootFiles = @('README.md', 'CLAUDE.md', 'CHANGELOG.md', 'LIMITATIONS.md', 'CONTRIBUTING.md', 'FORKING.md', 'SECURITY.md',
|
||||
'CODE_OF_CONDUCT.md', 'NOTICE', 'LICENSE', 'VERSION', 'build.ps1', 'global.json', 'FrameLedger.slnx', 'Directory.Build.props')
|
||||
|
||||
if ($Ref -notmatch '^[A-Za-z0-9][A-Za-z0-9._/-]*$') { throw "-Ref '$Ref' is not a branch, tag or commit name" }
|
||||
|
||||
# The anchor GitHub gives a heading: lower-case, letters, digits, '-' and '_' kept, a space a '-', the rest dropped
|
||||
# (MarkdownLinks.Slug in the App follows the same rule, so the guide's anchors work in both places).
|
||||
function Get-Slug([string]$Heading) {
|
||||
$sb = [System.Text.StringBuilder]::new()
|
||||
foreach ($c in $Heading.Trim().ToLowerInvariant().ToCharArray()) {
|
||||
if ([char]::IsLetterOrDigit($c) -or $c -eq '-' -or $c -eq '_') { [void]$sb.Append($c) }
|
||||
elseif ($c -eq ' ') { [void]$sb.Append('-') }
|
||||
}
|
||||
return $sb.ToString()
|
||||
}
|
||||
|
||||
# Lines outside fenced code blocks, each as @{ Index; Text }.
|
||||
function Get-ProseLines([string[]]$Lines) {
|
||||
$inFence = $false
|
||||
for ($i = 0; $i -lt $Lines.Count; $i++) {
|
||||
if ($Lines[$i] -match '^\s*(```|~~~)') { $inFence = -not $inFence; continue }
|
||||
if (-not $inFence) { [pscustomobject]@{ Index = $i; Text = $Lines[$i] } }
|
||||
}
|
||||
}
|
||||
|
||||
function Get-Anchors([string]$Text) {
|
||||
$anchors = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
|
||||
foreach ($line in Get-ProseLines (($Text -replace "`r`n", "`n") -split "`n")) {
|
||||
if ($line.Text -match '^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$') {
|
||||
$heading = [regex]::Replace($Matches[1], '\[([^\]]*)\]\([^)]*\)', '$1') -replace '[`*]', ''
|
||||
$slug = Get-Slug $heading
|
||||
if ($slug.Length -eq 0) { continue }
|
||||
$unique = $slug
|
||||
for ($n = 1; $anchors.Contains($unique); $n++) { $unique = "$slug-$n" }
|
||||
[void]$anchors.Add($unique)
|
||||
}
|
||||
}
|
||||
return , $anchors
|
||||
}
|
||||
|
||||
function Get-PageName([string]$Path, [string]$Text) {
|
||||
if ($special.ContainsKey($Path)) { return $special[$Path] }
|
||||
if ($Path.StartsWith('wiki/', [StringComparison]::Ordinal)) { return [IO.Path]::GetFileNameWithoutExtension($Path) }
|
||||
$h1 = @(($Text -replace "`r`n", "`n") -split "`n" | Where-Object { $_ -match '^# \S' }) | Select-Object -First 1
|
||||
if (-not $h1) { throw "$Path has no first heading to name its wiki page" }
|
||||
return (($h1.Substring(2).Trim() -replace '[^A-Za-z0-9]+', '-').Trim('-'))
|
||||
}
|
||||
|
||||
function Get-Sources([string]$SourceRoot) {
|
||||
$sources = [System.Collections.Generic.List[object]]::new()
|
||||
$add = {
|
||||
param([string]$Path, [string]$File)
|
||||
$text = [IO.File]::ReadAllText($File)
|
||||
$sources.Add([pscustomobject]@{ Path = $Path; Text = $text; Name = (Get-PageName $Path $text); FromWiki = $Path.StartsWith('wiki/', [StringComparison]::Ordinal) })
|
||||
}
|
||||
foreach ($f in Get-ChildItem (Join-Path $SourceRoot 'wiki') -Filter *.md -File | Sort-Object Name) { & $add "wiki/$($f.Name)" $f.FullName }
|
||||
foreach ($f in Get-ChildItem (Join-Path $SourceRoot 'guide') -Filter *.md -File | Sort-Object Name) { & $add "guide/$($f.Name)" $f.FullName }
|
||||
& $add 'LIMITATIONS.md' (Join-Path $SourceRoot 'LIMITATIONS.md')
|
||||
return , $sources
|
||||
}
|
||||
|
||||
# A link's target as a path from the repository root, or $null when it climbs out of it.
|
||||
function Resolve-RepoPath([string]$From, [string]$Link) {
|
||||
$parts = [System.Collections.Generic.List[string]]::new()
|
||||
$dir = [IO.Path]::GetDirectoryName($From) -replace '\\', '/'
|
||||
if ($dir) { foreach ($s in $dir -split '/') { $parts.Add($s) } }
|
||||
foreach ($seg in ($Link -split '/')) {
|
||||
if ($seg -eq '' -or $seg -eq '.') { continue }
|
||||
if ($seg -eq '..') {
|
||||
if ($parts.Count -eq 0) { return $null }
|
||||
$parts.RemoveAt($parts.Count - 1)
|
||||
continue
|
||||
}
|
||||
$parts.Add($seg)
|
||||
}
|
||||
return ($parts -join '/')
|
||||
}
|
||||
|
||||
# Every inline link of a page outside code: @{ Start; Length; Href }, in order.
|
||||
function Get-Links([string]$Text) {
|
||||
$lines = $Text -split "`n"
|
||||
$offsets = [int[]]::new($lines.Count)
|
||||
$at = 0
|
||||
for ($i = 0; $i -lt $lines.Count; $i++) { $offsets[$i] = $at; $at += $lines[$i].Length + 1 }
|
||||
foreach ($line in Get-ProseLines $lines) {
|
||||
foreach ($m in [regex]::Matches($line.Text, '(?<!!)\]\((?<href>[^)\s]+)(?:\s+"[^"]*")?\)')) {
|
||||
$g = $m.Groups['href']
|
||||
[pscustomobject]@{ Start = $offsets[$line.Index] + $g.Index; Length = $g.Length; Href = $g.Value }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Assembles the wiki in memory: @{ Pages = name -> text; Problems = string[] }.
|
||||
function Invoke-Assembly([string]$SourceRoot, [string]$Root, [string]$GitRef) {
|
||||
$problems = [System.Collections.Generic.List[string]]::new()
|
||||
$sources = Get-Sources $SourceRoot
|
||||
$byPath = @{}
|
||||
$byName = @{}
|
||||
foreach ($s in $sources) {
|
||||
$byPath[$s.Path] = $s
|
||||
if ($byName.ContainsKey($s.Name)) { $problems.Add("$($s.Path) and $($byName[$s.Name].Path) both make the page '$($s.Name)'") }
|
||||
else { $byName[$s.Name] = $s }
|
||||
}
|
||||
foreach ($req in 'Home', '_Sidebar') {
|
||||
if (-not $byName.ContainsKey($req)) { $problems.Add("wiki/$req.md is missing") }
|
||||
}
|
||||
|
||||
$anchorCache = @{}
|
||||
$anchorsOf = {
|
||||
param([string]$Path, [string]$Text)
|
||||
if (-not $anchorCache.ContainsKey($Path)) { $anchorCache[$Path] = Get-Anchors $Text }
|
||||
return , $anchorCache[$Path]
|
||||
}
|
||||
|
||||
$pages = [ordered]@{}
|
||||
$edges = @{}
|
||||
foreach ($s in $sources) {
|
||||
$text = $s.Text -replace "`r`n", "`n"
|
||||
$targets = [System.Collections.Generic.List[string]]::new()
|
||||
$links = @(Get-Links $text)
|
||||
$sb = [System.Text.StringBuilder]::new($text)
|
||||
for ($k = $links.Count - 1; $k -ge 0; $k--) {
|
||||
$link = $links[$k]
|
||||
$href = $link.Href
|
||||
if ($href -match '^(https?:|mailto:)') { continue }
|
||||
$hash = $href.IndexOf('#')
|
||||
$anchor = if ($hash -ge 0) { $href.Substring($hash + 1) } else { $null }
|
||||
$pathPart = if ($hash -ge 0) { $href.Substring(0, $hash) } else { $href }
|
||||
$new = $null
|
||||
if ($pathPart -eq '') {
|
||||
if (-not $anchor -or -not (& $anchorsOf $s.Path $s.Text).Contains($anchor.ToLowerInvariant())) { $problems.Add("$($s.Path): '$href' names no section of the page") }
|
||||
continue
|
||||
}
|
||||
$isDir = $pathPart.EndsWith('/')
|
||||
$target = Resolve-RepoPath $s.Path ([Uri]::UnescapeDataString($pathPart))
|
||||
if ($null -eq $target -or $target -eq '') { $problems.Add("$($s.Path): '$href' leaves the repository"); continue }
|
||||
if ($byPath.ContainsKey($target)) {
|
||||
$page = $byPath[$target]
|
||||
if ($anchor -and -not (& $anchorsOf $page.Path $page.Text).Contains($anchor.ToLowerInvariant())) { $problems.Add("$($s.Path): '$href' names no section of $target") }
|
||||
$new = $page.Name + $(if ($anchor) { "#$anchor" } else { '' })
|
||||
$targets.Add($page.Name)
|
||||
}
|
||||
else {
|
||||
$full = Join-Path $Root ($target -replace '/', [IO.Path]::DirectorySeparatorChar)
|
||||
$exists = if ($isDir) { Test-Path -LiteralPath $full -PathType Container } else { Test-Path -LiteralPath $full }
|
||||
if (-not $exists) { $problems.Add("$($s.Path): '$href' leads to $target, which does not exist"); continue }
|
||||
$folder = Test-Path -LiteralPath $full -PathType Container
|
||||
if ($anchor -and ($folder -or -not $target.EndsWith('.md') -or -not (& $anchorsOf $target ([IO.File]::ReadAllText($full))).Contains($anchor.ToLowerInvariant()))) {
|
||||
$problems.Add("$($s.Path): '$href' names no section of $target")
|
||||
}
|
||||
$kind = if ($folder) { 'tree' } else { 'blob' }
|
||||
$new = "$repoUrl/$kind/$GitRef/$($target.TrimEnd('/'))" + $(if ($anchor) { "#$anchor" } else { '' })
|
||||
}
|
||||
[void]$sb.Remove($link.Start, $link.Length).Insert($link.Start, $new)
|
||||
}
|
||||
|
||||
# The wiki prints the page's name as its title; the source's own first heading - kept for reading it in the
|
||||
# repository and, for a guide page, in the App - would repeat it.
|
||||
$converted = [regex]::Replace($sb.ToString(), '\A(?:<!--.*?-->\s*)*# [^\n]*\n(\s*\n)?', '', [Text.RegularExpressions.RegexOptions]::Singleline)
|
||||
if ($s.FromWiki) { Test-WikiSource $s $Root $problems }
|
||||
|
||||
$pages[$s.Name] = $converted
|
||||
$edges[$s.Name] = $targets
|
||||
}
|
||||
|
||||
Test-Reachable $edges $byName $problems
|
||||
Test-SidebarOrder $byPath $problems
|
||||
$pages['_Footer'] = "This wiki is generated from the repository at [``$GitRef``]($repoUrl/tree/$GitRef). Edit " +
|
||||
"[``wiki/``]($repoUrl/tree/main/wiki) or [``guide/``]($repoUrl/tree/main/guide) there: a change made here is " +
|
||||
"overwritten when the next release is published.`n"
|
||||
return [pscustomobject]@{ Pages = $pages; Problems = $problems.ToArray() }
|
||||
}
|
||||
|
||||
# A wiki/ page names only paths that exist, and no version number.
|
||||
function Test-WikiSource($Source, [string]$Root, $Problems) {
|
||||
foreach ($line in Get-ProseLines (($Source.Text -replace "`r`n", "`n") -split "`n")) {
|
||||
foreach ($m in [regex]::Matches($line.Text, '`([^`\s]+)`')) {
|
||||
$candidate = $m.Groups[1].Value.TrimEnd('.', ',', ';', ':')
|
||||
$isPath = ($pathPrefixes | Where-Object { $candidate.StartsWith($_, [StringComparison]::Ordinal) }) -or ($rootFiles -contains $candidate)
|
||||
if (-not $isPath -or $candidate -match '[*<>{}|?]') { continue }
|
||||
$full = Join-Path $Root ($candidate.TrimEnd('/') -replace '/', [IO.Path]::DirectorySeparatorChar)
|
||||
if (-not (Test-Path -LiteralPath $full)) { $Problems.Add("$($Source.Path): ``$candidate`` names nothing in the repository") }
|
||||
}
|
||||
if ($line.Text -match '\b\d+\.\d+\.\d+-(?:beta|rc|alpha)\.\d+\b') {
|
||||
$Problems.Add("$($Source.Path): '$($Matches[0])' - a wiki page names no version; the footer says which release it shows")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function Test-Reachable($Edges, $ByName, $Problems) {
|
||||
$seen = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
|
||||
$queue = [System.Collections.Generic.Queue[string]]::new()
|
||||
foreach ($start in 'Home', '_Sidebar') { if ($ByName.ContainsKey($start) -and $seen.Add($start)) { $queue.Enqueue($start) } }
|
||||
while ($queue.Count -gt 0) {
|
||||
foreach ($next in $Edges[$queue.Dequeue()]) { if ($seen.Add($next)) { $queue.Enqueue($next) } }
|
||||
}
|
||||
foreach ($name in $ByName.Keys | Sort-Object) {
|
||||
if (-not $seen.Contains($name)) { $Problems.Add("$($ByName[$name].Path): no link from Home or the sidebar leads to '$name'") }
|
||||
}
|
||||
}
|
||||
|
||||
# The sidebar lists the guide's pages in the order of the guide's own contents.
|
||||
function Test-SidebarOrder($ByPath, $Problems) {
|
||||
if (-not $ByPath.ContainsKey('wiki/_Sidebar.md') -or -not $ByPath.ContainsKey('guide/README.md')) { return }
|
||||
$order = {
|
||||
param($Source)
|
||||
$paths = foreach ($l in Get-Links ($Source.Text -replace "`r`n", "`n")) {
|
||||
$hash = $l.Href.IndexOf('#')
|
||||
$p = Resolve-RepoPath $Source.Path ([Uri]::UnescapeDataString($(if ($hash -ge 0) { $l.Href.Substring(0, $hash) } else { $l.Href })))
|
||||
if ($p -and $p.StartsWith('guide/', [StringComparison]::Ordinal) -and $p -ne 'guide/README.md') { $p }
|
||||
}
|
||||
return @($paths | Select-Object -Unique)
|
||||
}
|
||||
$contents = & $order $ByPath['guide/README.md']
|
||||
$sidebar = & $order $ByPath['wiki/_Sidebar.md']
|
||||
if (($contents -join '|') -ne ($sidebar -join '|')) {
|
||||
$Problems.Add("wiki/_Sidebar.md lists the guide as [$($sidebar -join ', ')], guide/README.md as [$($contents -join ', ')]")
|
||||
}
|
||||
}
|
||||
|
||||
function Write-Wiki($Pages, [string]$Folder) {
|
||||
New-Item -ItemType Directory -Path $Folder -Force | Out-Null
|
||||
Get-ChildItem -LiteralPath $Folder -Force | Where-Object { $_.Name -ne '.git' } | Remove-Item -Recurse -Force
|
||||
$utf8 = [System.Text.UTF8Encoding]::new($false)
|
||||
foreach ($name in $Pages.Keys) {
|
||||
[IO.File]::WriteAllText((Join-Path $Folder "$name.md"), ($Pages[$name] -replace "`r`n", "`n"), $utf8)
|
||||
}
|
||||
}
|
||||
|
||||
if ($SelfTest) {
|
||||
$tmp = Join-Path ([IO.Path]::GetTempPath()) ('fl-wiki-' + [Guid]::NewGuid().ToString('N'))
|
||||
New-Item -ItemType Directory -Path $tmp | Out-Null
|
||||
try {
|
||||
Copy-Item (Join-Path $RepoRoot 'wiki') (Join-Path $tmp 'wiki') -Recurse
|
||||
Copy-Item (Join-Path $RepoRoot 'guide') (Join-Path $tmp 'guide') -Recurse
|
||||
Copy-Item (Join-Path $RepoRoot 'LIMITATIONS.md') $tmp
|
||||
$cases = 0
|
||||
$expect = {
|
||||
param([string]$What, [string]$Pattern)
|
||||
$p = @((Invoke-Assembly $tmp $RepoRoot $Ref).Problems)
|
||||
if ($Pattern -eq '') {
|
||||
if ($p.Count -ne 0) { throw "self-test: $What should pass, got: $($p -join '; ')" }
|
||||
}
|
||||
elseif ($p.Count -ne 1 -or $p[0] -notmatch $Pattern) { throw "self-test: $What should fail once matching '$Pattern', got: $($p -join '; ')" }
|
||||
$script:cases++
|
||||
}
|
||||
$mutate = {
|
||||
param([string]$Rel, [scriptblock]$Change, [string]$What, [string]$Pattern)
|
||||
$file = Join-Path $tmp $Rel
|
||||
$existed = Test-Path $file
|
||||
$orig = if ($existed) { [IO.File]::ReadAllText($file) } else { $null }
|
||||
[IO.File]::WriteAllText($file, (& $Change $orig))
|
||||
try { & $expect $What $Pattern }
|
||||
finally { if ($existed) { [IO.File]::WriteAllText($file, $orig) } else { Remove-Item $file } }
|
||||
}
|
||||
|
||||
& $expect 'the shipped sources' ''
|
||||
& $mutate 'wiki/Home.md' { param($t) $t + "`n[gone](../docs/NO_SUCH_FILE.md)`n" } 'a link to a missing file' 'NO_SUCH_FILE.*does not exist'
|
||||
& $mutate 'wiki/Home.md' { param($t) $t + "`n[gone](../guide/01-install.md#no-such-section)`n" } 'a link to a missing section' 'no-such-section.*names no section'
|
||||
& $mutate 'wiki/Home.md' { param($t) $t + "`n[out](../../outside.md)`n" } 'a link out of the repository' 'leaves the repository'
|
||||
& $mutate 'wiki/Limitations.md' { param($t) "Same name as LIMITATIONS.md.`n" } 'two sources for one page' "both make the page 'Limitations'"
|
||||
& $mutate 'wiki/Orphan.md' { param($t) "Nothing links here.`n" } 'a page nothing leads to' "leads to 'Orphan'"
|
||||
& $mutate 'wiki/_Sidebar.md' { param($t) ($t -replace '(?m)^- \[Questions and answers\]\(\.\./guide/06-faq\.md\)\r?\n', '') + "- [Questions and answers](../guide/06-faq.md)`n" } 'a sidebar out of the guide''s order' 'lists the guide as'
|
||||
& $mutate 'wiki/Home.md' { param($t) $t + "`nSee ``src/FrameLedger.App/NoSuchFile.cs``.`n" } 'a backticked path that names nothing' 'NoSuchFile\.cs.*names nothing'
|
||||
& $mutate 'wiki/Home.md' { param($t) $t + "`nSince 0.1.0-beta.99.`n" } 'a version number in a page' 'names no version'
|
||||
Write-Host "wiki-build self-test OK - $cases cases, both directions"
|
||||
}
|
||||
finally {
|
||||
Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue
|
||||
}
|
||||
exit 0
|
||||
}
|
||||
|
||||
$result = Invoke-Assembly $RepoRoot $RepoRoot $Ref
|
||||
if ($result.Problems.Count -ne 0) {
|
||||
Write-Host 'WIKI CHECK FAILED:' -ForegroundColor Red
|
||||
foreach ($p in $result.Problems) { Write-Host " $p" -ForegroundColor Red }
|
||||
Write-Host ' The wiki is built from wiki/, guide/ and LIMITATIONS.md (docs/13_CI_CD.md, wiki.yml).' -ForegroundColor Red
|
||||
exit 1
|
||||
}
|
||||
if ($Check) {
|
||||
$tmp = Join-Path ([IO.Path]::GetTempPath()) ('fl-wiki-check-' + [Guid]::NewGuid().ToString('N'))
|
||||
try { Write-Wiki $result.Pages $tmp } finally { Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue }
|
||||
Write-Host "wiki-check OK - $($result.Pages.Count) pages, every link leads somewhere"
|
||||
exit 0
|
||||
}
|
||||
if (-not $Out) { $Out = Join-Path $RepoRoot 'out/wiki' }
|
||||
Write-Wiki $result.Pages $Out
|
||||
Write-Host "wiki-build OK - $($result.Pages.Count) pages written to $Out at $Ref"
|
||||
exit 0
|
||||
@@ -0,0 +1,48 @@
|
||||
# App UI development
|
||||
|
||||
The screens are specified, and described as built, in [`docs/08_UI.md`](../docs/08_UI.md); the rules for the UI library
|
||||
are [`docs/16_WPFUI_SYNTAX.md`](../docs/16_WPFUI_SYNTAX.md). The App is `src/FrameLedger.App`: WPF on .NET 10 with
|
||||
WPF UI 4.3.0 (pinned), CommunityToolkit.Mvvm, ScottPlot for charts and Markdig for documents.
|
||||
|
||||
## How it is put together
|
||||
|
||||
- A .NET Generic Host with dependency injection. Pages and their view models are transient — a page is made again on
|
||||
every navigation, so state lives in the view models' services and the database, never in a page.
|
||||
- Navigation goes only through WPF UI's `INavigationService`; a page implements `INavigableView<TViewModel>`.
|
||||
- The App opens `ledger.db` itself to read; anything that acts on the PC — hooking, deleting sessions, pausing — is a
|
||||
request to the agent over the pipe.
|
||||
- `FrameLedger.exe --data-dir <copy>` is a viewer: no agent, no update, the controls that would change the PC disabled.
|
||||
|
||||
## Strings
|
||||
|
||||
Every user-visible string comes from `.resx`, in English, Vietnamese and Japanese (`src/FrameLedger.App/Strings.resx`
|
||||
and its `.vi` and `.ja` siblings; the shared ones are in `src/FrameLedger.Shared`). `tools/resx-gen.ps1` writes the
|
||||
accessor class, and `tools/resx-audit.ps1` fails the build when a key is missing in a language. The safety texts in
|
||||
Japanese wait for a human reviewer, never a machine draft ([`docs/09_I18N.md`](../docs/09_I18N.md)).
|
||||
|
||||
## Colours and theme
|
||||
|
||||
Colours come only from WPF UI's theme brushes, by `DynamicResource` — never a hex value, never `StaticResource` for a
|
||||
theme brush. Muted text uses the App's `SecondaryText` and `TertiaryText` styles (`src/FrameLedger.App/Styles/FrameLedger.xaml`).
|
||||
The chart palettes are the one place a colour is written out, once per theme.
|
||||
|
||||
## The traps of WPF UI 4.3.0
|
||||
|
||||
Each of these cost a release; the full list, with the tests that hold each, is §Gotchas checklist of
|
||||
[`docs/16_WPFUI_SYNTAX.md`](../docs/16_WPFUI_SYNTAX.md).
|
||||
|
||||
- `ui:TextBlock Appearance=` looks its brush up once: a theme switch leaves the text in the old theme's colour.
|
||||
- A class handler on `Loaded` does not reach every element: WPF raises Loaded only where a subtree listens for it.
|
||||
- Every page sets `ScrollViewer.CanContentScroll="False"`, or WPF UI wraps it in a scroller that eats the mouse wheel;
|
||||
a scroller inside a dialog is a `ui:PassiveScrollViewer`.
|
||||
- A scroll bar is hidden through its scroller's own `ScrollBarVisibility`, never a style on the bar.
|
||||
- `ui:InfoBar` draws no content (the App's copy of its template does); `ui:Badge` palette appearances are not theme
|
||||
colours; WPF UI's DataGrid parts have keyed styles only; its CheckBox is 120 px wide at least.
|
||||
- No dialog closes on Esc by itself (`Services/DialogKeyboard` does it); ScottPlot zooms on every wheel unless told not to.
|
||||
- Apply the theme before the first window loads; watch the system theme only once the window has a handle.
|
||||
|
||||
## Testing the UI
|
||||
|
||||
`tests/FrameLedger.App.Tests` renders every page, window and dialog under the real theme dictionaries on one STA thread
|
||||
(`PagesLoadTests.OnStaAsync`): contrast in both themes, a theme switch while a surface is on screen, scroll bars with the
|
||||
option on in a real window, keyboard and automation names. A rendered check is run red against the unfixed XAML first.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Architecture
|
||||
|
||||
The full document is [`docs/01_ARCHITECTURE.md`](../docs/01_ARCHITECTURE.md); the IPC details are in
|
||||
[`docs/07_IPC.md`](../docs/07_IPC.md).
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph game["Game process (only games the user enabled)"]
|
||||
G["Game"] -- "present and API calls" --> O["FrameLedger.Overlay.dll: hooks"]
|
||||
end
|
||||
O -- "fixed-size frame records" --> R[("shared-memory ring")]
|
||||
R -- "drained every 100 ms" --> A["FrameLedger.Agent.exe"]
|
||||
A -- "sessions, frames, sensors" --> DB[("ledger.db (SQLite)")]
|
||||
DB --> UI["FrameLedger.exe (the App)"]
|
||||
UI -- "named pipe: commands" --> A
|
||||
A -- "named pipe: events" --> UI
|
||||
```
|
||||
|
||||
## The processes
|
||||
|
||||
| What | Runs | Does |
|
||||
|---|---|---|
|
||||
| `FrameLedger.exe` — `src/FrameLedger.App` | as the user | The WPF app: library, sessions, charts, settings. Reads SQLite; talks to the agent over the pipe. |
|
||||
| `FrameLedger.Agent.exe` — `src/FrameLedger.Agent` | as the user; as administrator only if the user opts in | Watches for tracked games, runs the anti-cheat guard, injects, drains the ring, reads sensors once a second, writes SQLite. Closing the App never stops it. |
|
||||
| `FrameLedger.Overlay.dll` — `src/native/FrameLedger.Overlay` | inside the game | Hooks presentation (DXGI for Direct3D 11 and 12, and OpenGL) and the upscaler, frame-generation and ray-tracing calls, and writes one record per frame into the ring. A hook never blocks, allocates, logs or throws. It draws nothing on screen. |
|
||||
| `FrameLedger.VkLayer.dll` — `src/native/FrameLedger.VkLayer` | inside a Vulkan game | An implicit Vulkan layer instead of hooks, active only in a game FrameLedger starts. |
|
||||
| `FrameLedger.Guard.dll`, `FrameLedger.NvapiBridge.dll`, `FrameLedger.ProcessStats.dll` | inside the agent, never a game | The anti-cheat guard (required), NVIDIA's extra sensors (optional), and the game's own memory read from outside it (optional). An optional one missing makes its fields N/A. |
|
||||
|
||||
`src/FrameLedger.CaptureHost` is a developer tool and is never shipped.
|
||||
|
||||
## Two tiers
|
||||
|
||||
- **Tier 1 — measured.** The user switched hooking on for the game, and the guard found nothing: every frame is
|
||||
recorded.
|
||||
- **Tier 2 — recorded only.** No hooking: the session keeps its duration, the PC's sensors, the game's memory, its
|
||||
display mode, and *why* it was not measured. Every frame figure is N/A, never an estimate.
|
||||
|
||||
There is no third rung: without the hook there is no frame measurement at all.
|
||||
|
||||
## How a frame gets to the screen
|
||||
|
||||
1. The agent's watcher sees a tracked game's executable start (by full path, once a second).
|
||||
2. Hooking off, or not consented: the session is Tier 2.
|
||||
3. The guard checks the game's process tree, the PC's drivers and services, its title lists and the game's install
|
||||
folder. Any finding, or any doubt, refuses: Tier 2, with the reason.
|
||||
4. On a pass, the guard injects the Overlay with the documented `LoadLibraryW`, under its real name.
|
||||
5. The Overlay installs its hooks, creates the ring and publishes a handshake; the agent checks the layout version and
|
||||
the build id before it reads anything.
|
||||
6. The agent drains the ring every 100 ms and checks the game again every 30 seconds; a finding unhooks.
|
||||
7. When the game exits, the agent finalizes the session and writes it to SQLite in one transaction; the App reads it.
|
||||
|
||||
## Where data lives
|
||||
|
||||
`%LOCALAPPDATA%\FrameLedger`: `ledger.db` (WAL mode), `logs\`, `crashdumps\`, and `tmp\` for a session in progress
|
||||
(its `.partial` file). The App installs separately, in `%LOCALAPPDATA%\FrameLedger.App`.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Build and test
|
||||
|
||||
The full documents are [`docs/12_BUILD.md`](../docs/12_BUILD.md) and [`docs/14_TESTING.md`](../docs/14_TESTING.md).
|
||||
|
||||
## What you need
|
||||
|
||||
- Windows 10 (22H2) or 11, 64-bit.
|
||||
- Visual Studio with the C++ workload (MSVC v143 or later, a Windows SDK of 22621 or later) and CMake 3.28 or later.
|
||||
- The .NET SDK that [`global.json`](../global.json) pins.
|
||||
- PowerShell 7.
|
||||
|
||||
## The one gate
|
||||
|
||||
```powershell
|
||||
./build.ps1 check
|
||||
```
|
||||
|
||||
It is the whole gate, and CI runs the same script. In order:
|
||||
|
||||
| Step | What fails it |
|
||||
|---|---|
|
||||
| Native build and ctest | A C++ warning (`/W4 /WX`) or a native test. |
|
||||
| clang-format, `dotnet format` | Code not formatted as committed. |
|
||||
| Managed build and tests | A C# warning (warnings are errors), or a test — the integration tests included. |
|
||||
| coverage-gate | Too little coverage of Domain and Application. |
|
||||
| rules-validate | A detection-rules file that breaks its schema or weakens the anti-cheat blocklist. |
|
||||
| versioninfo, chokepoint, hookinventory, package-closure | A binary without its version resources; an injection anywhere but the guard's own code, or an evasion primitive anywhere; a hook not in the inventory; a developer tool in the package. |
|
||||
| license-check, accuracy-check, notice-check | A package without its licence, a copy of the accuracy statement that drifted, a source file without its licence header. |
|
||||
| changelog-check, release-notes, resx-audit | The changelog or the release-notes extractor broken, or a string missing in English, Vietnamese or Japanese. |
|
||||
| struct-mirror, test-artifacts, wiki-check, placeholder guard | The shared-memory mirror test not run, test leftovers, a wiki link that leads nowhere, a stray `{{…}}` in a shipped document. |
|
||||
|
||||
Other tasks: `./build.ps1 native`, `./build.ps1 managed`, `./build.ps1 format` (writes the formatting). A skipped gate is
|
||||
reported, never hidden.
|
||||
|
||||
## Tests
|
||||
|
||||
- **Managed:** one project per layer under `tests/` (xUnit v3, FluentAssertions). The App's tests render every page,
|
||||
window and dialog under the real theme dictionaries.
|
||||
- **Native:** ctest suites for the guard, the ring, the layout, the Vulkan layer, the telemetry DLLs.
|
||||
- **Integration:** the hook-harness is hooked for real, on WARP, so it runs on CI without a GPU.
|
||||
- **A new test is shown red first** on the unfixed code: a check that has never failed has not been seen to work.
|
||||
|
||||
## Looking at the App with real data
|
||||
|
||||
`FrameLedger.exe --data-dir <a copy of a data folder>` opens the App as a viewer: no agent is started or contacted, and
|
||||
nothing on the PC is changed. **Never run a development build against your own `%LOCALAPPDATA%\FrameLedger`**: a newer
|
||||
build upgrades the database, and an older one cannot open it again.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Capture pipeline
|
||||
|
||||
What the agent does from the moment a game starts. The full document is [`docs/04_CAPTURE.md`](../docs/04_CAPTURE.md);
|
||||
the guard is [`docs/19_SAFETY_AND_ANTICHEAT.md`](../docs/19_SAFETY_AND_ANTICHEAT.md); the code is in
|
||||
`src/FrameLedger.Application/Capture`, `src/FrameLedger.Application/Recording` and `src/FrameLedger.Application/Watch`.
|
||||
|
||||
## Watching
|
||||
|
||||
- Once a second, the watcher lists the running processes and matches each executable's **full path** against the
|
||||
library entries that have recording on. A file name alone never starts a session — except the same file on a
|
||||
changed drive letter, which the agent follows.
|
||||
- A launcher's consent does not carry over to the game it starts: the game's own executable is the one that counts.
|
||||
- One session per game at a time. At every start, the agent first rebuilds any session a crash interrupted.
|
||||
|
||||
## A session's life
|
||||
|
||||
`Idle → Detected → Guarded → Injecting → Capturing → Finalizing → Saved`, with three side roads:
|
||||
|
||||
- **Refused** — the guard found something, or hooking is off: the session continues as Tier 2, with the reason.
|
||||
- **Unhooked for safety** — a finding at a 30-second re-scan: the hook goes dormant (it is never unloaded), measuring
|
||||
stops, and the session keeps the frames measured so far and says it stopped early.
|
||||
- **Interrupted** — the agent itself stopped: its `.partial` file is turned into a session at the next start.
|
||||
|
||||
A session shorter than the minimum length (30 seconds by default) is discarded.
|
||||
|
||||
## While capturing
|
||||
|
||||
- The ring is drained every 100 ms; it holds about 16 seconds of frames at 500 fps, so a stall of the agent loses
|
||||
nothing, and a dropped record is a warning on the session, never silently accepted.
|
||||
- Sensors are read on their own thread once a second, through three layers: Windows itself (DXGI and performance
|
||||
counters, any GPU), LibreHardwareMonitor (any GPU), and NVAPI (NVIDIA cards). A missing layer makes its fields N/A.
|
||||
- The game's own video memory and RAM are read from outside the game, in both tiers.
|
||||
- Everything is written to the session's `.partial` file at each step and every 60 seconds.
|
||||
|
||||
## Ending
|
||||
|
||||
- The last drain, then one SQLite transaction writes the session, its segments, its frame and sensor series.
|
||||
- How the game ended is classified: *normal*; *crashed* (an exception exit code, an application-error event in the
|
||||
window, or the game's own crash reporter starting late); *unhooked for safety*; *degraded* (the hook faulted or lost
|
||||
the game); *interrupted*.
|
||||
- Two abnormal ends within 60 seconds of attaching switch hooking off for that game, and nothing switches it back on
|
||||
automatically.
|
||||
|
||||
Why a session ended is the `SessionEndReason` type in `src/FrameLedger.Application/Capture` — the list grows, so read
|
||||
the code rather than a copy of it.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Contributor rules
|
||||
|
||||
The rules are stated in full, with their amendments, in [`CLAUDE.md`](../CLAUDE.md) §Non-negotiable rules; the safety
|
||||
policy behind them is [`docs/19_SAFETY_AND_ANTICHEAT.md`](../docs/19_SAFETY_AND_ANTICHEAT.md). In plain words:
|
||||
|
||||
## The nine rules
|
||||
|
||||
1. **Hooking is opt-in, per game.** The user adds the game *and* switches hooking on for it, after a warning. There is
|
||||
no "hook everything" mode and no automatic injection.
|
||||
2. **The anti-cheat guard is a gate, not a warning.** It checks before every injection and every 30 seconds after. A
|
||||
finding refuses, says why, and switches the game's hooking off. There is no override — apart from one narrow,
|
||||
evidence-bound exception for anti-cheat that runs entirely in user mode, which the user grants per game and which
|
||||
ends for good the first time it goes wrong. Do not add another form of override.
|
||||
3. **No evasion.** Injection uses the documented `LoadLibraryW`; the component keeps its real name, exports and version
|
||||
information. A performance tool must be *visible* to anti-cheat. A change that makes FrameLedger harder to detect is
|
||||
refused on principle.
|
||||
4. **Never read or write game memory** beyond the arguments of the calls we hooked and the objects we own.
|
||||
5. **The hook must never crash the game.** Every hook body is guarded, allocates nothing, takes no lock, logs nothing
|
||||
and lets no exception out; repeated faults switch the hook off.
|
||||
6. **Never one inflated frame rate.** With frame generation measured, Native, Displayed and the factor are shown
|
||||
together; without it, *Presented FPS* with a sentence saying whether generated frames could be in it
|
||||
([Metrics](Metrics.md)).
|
||||
7. **Ray tracing, path tracing and ray reconstruction are Yes, No or N/A.** Where it cannot be measured, the answer is
|
||||
N/A — never a made-up Yes.
|
||||
8. **No telemetry, no analytics, no silent network calls.** The rule permits three requests — the update check, a
|
||||
detection-rules fetch and store metadata the user opts into. Only the update check, and its download, exists today,
|
||||
and the user can switch it off.
|
||||
9. **No obfuscation of our own binaries.** GPL v3; releases ship with SHA-256 checksums.
|
||||
|
||||
## What will never be built
|
||||
|
||||
Manual mapping or reflective loading; erasing PE headers; unlinking from the module list; hiding, renaming or
|
||||
randomising the component, its exports or its object names; hiding threads or evading debuggers; packing; any bypass or
|
||||
stealth mode, or instructions to defeat the guard; reading game state; a kernel driver of our own. A pull request that
|
||||
proposes one is closed with a pointer to the safety document.
|
||||
|
||||
## Every pull request
|
||||
|
||||
The checklist is [`.github/pull_request_template.md`](../.github/pull_request_template.md):
|
||||
|
||||
- `./build.ps1 check` passes — no warning in C# or C++, every test green, formatting clean.
|
||||
- A document a change makes wrong is corrected **in the same pull request**. A stale sentence is struck through and
|
||||
dated where it stands, not quietly rewritten.
|
||||
- Every new user-visible string exists in English, Vietnamese and Japanese (`.resx`).
|
||||
- Every first-party source file opens with the two-line licence header that [`NOTICE`](../NOTICE) explains
|
||||
(`tools/notice-check.ps1 -Fix` writes it).
|
||||
- A change to `src/` adds a line to `CHANGELOG.md` `[Unreleased]`.
|
||||
- A change to the hook layer states its measured overhead, lists any new hook in the inventory
|
||||
([`docs/17_HOOK_ENGINE.md`](../docs/17_HOOK_ENGINE.md)) and answers the safety review questions in the template.
|
||||
- A user-visible limit that moves updates [`LIMITATIONS.md`](../LIMITATIONS.md) in the same pull request.
|
||||
|
||||
How to contribute and how contributions are licensed: [`CONTRIBUTING.md`](../CONTRIBUTING.md).
|
||||
@@ -0,0 +1,45 @@
|
||||
# Data and IPC
|
||||
|
||||
The full documents are [`docs/06_DATA_MODEL.md`](../docs/06_DATA_MODEL.md) and [`docs/07_IPC.md`](../docs/07_IPC.md).
|
||||
|
||||
## The database
|
||||
|
||||
One SQLite file, `%LOCALAPPDATA%\FrameLedger\ledger.db`, in WAL mode, used through Microsoft.Data.Sqlite and Dapper.
|
||||
|
||||
| Table | Holds |
|
||||
|---|---|
|
||||
| `games` | The library, with each game's hooking, consent and anti-cheat state. |
|
||||
| `sessions` | One row per session: its tier, how it ended, its figures. |
|
||||
| `session_segments` | Spans of a session at one resolution and upscaler. |
|
||||
| `frame_blobs`, `sensor_blobs` | The per-frame and sensor series, compressed. |
|
||||
| `hardware_snapshots` | The PC as it was, shared by the sessions recorded on it. |
|
||||
| `session_annotations` | Tags, notes and the user's overrides. |
|
||||
| `settings` | Key and value, as `SettingsRegistry` (`src/FrameLedger.Application/Settings`) defines them. |
|
||||
| `legal_acceptance` | Which version of each document the user accepted, and when. |
|
||||
| `schema_migrations` | The migrations applied. |
|
||||
|
||||
- **Who writes what:** the agent writes sessions, their series and snapshots, and a game's hooking state; the App
|
||||
writes what the user edits — a game's details, annotations, settings, legal acceptance. Consent never goes through
|
||||
the database: the App asks the agent over the pipe.
|
||||
- **Migrations** are numbered SQL files embedded in `src/FrameLedger.Infrastructure/Persistence/Migrations`, applied in
|
||||
order by whichever process opens the file first, under a lock. A database newer than the build is refused, which is
|
||||
why an older version cannot open a database a newer one has touched.
|
||||
|
||||
## Shared memory — the game and the agent
|
||||
|
||||
- One mapping per game process, created by the component in the game and opened by the agent: a handshake, the
|
||||
writer's state, a control block, the display state, then a ring of fixed-size frame records — one writer, one reader,
|
||||
no locks.
|
||||
- The layout is defined twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (normative) and
|
||||
`src/FrameLedger.Shared/ShmLayout.cs`. `ShmLayoutMirrorTests` compares every field's offset against JSON the native
|
||||
`fl-layout-dump` writes, in both directions, and the gate fails if that test did not run.
|
||||
- Before reading anything, the agent compares the layout version, the record size and the build id, and refuses to
|
||||
attach on a mismatch.
|
||||
|
||||
## The pipe — the App and the agent
|
||||
|
||||
- A named pipe, `\\.\pipe\FrameLedger.v2`, carrying length-prefixed JSON messages (source-generated System.Text.Json,
|
||||
unknown fields ignored): commands from the App (switch hooking on, pause, delete sessions…) and events from the agent
|
||||
(a session started, made progress, ended; a safety notice).
|
||||
- **The pipe is not a trust boundary for safety:** no message can tell the agent that something is safe. The guard
|
||||
decides on its own.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Developer glossary
|
||||
|
||||
The words the code and the documents use. The player's glossary is [Words FrameLedger uses](../guide/10-glossary.md).
|
||||
|
||||
- **Agent** — `FrameLedger.Agent.exe`, the capture orchestrator; `--serve` is its normal mode, `--console` the
|
||||
developer's.
|
||||
- **Census** — the frame-generation runtimes found loaded in a game; it decides the qualifier beside Presented FPS.
|
||||
- **Consent** — a user's per-game agreement to hooking, typed in the consent dialog, stamped with where it came from.
|
||||
- **D-numbers** (D1, D2, …) — the owner's decisions, recorded in [`docs/HANDOFF.md`](../docs/HANDOFF.md).
|
||||
- **Drain** — the agent reading the ring, every 100 ms.
|
||||
- **FR-x / NFR-x** — requirement ids from [`docs/02_SPEC.md`](../docs/02_SPEC.md).
|
||||
- **Guard** — the native anti-cheat check that runs before every injection and every 30 seconds after; one
|
||||
implementation, in `src/native/FrameLedger.Injector`.
|
||||
- **Handshake** — the first region of the shared memory: layout version, record size and build id, checked before
|
||||
anything is read.
|
||||
- **Hook harness** — `src/native/tools/hook-harness`, a dummy Direct3D 11, Direct3D 12, Vulkan and OpenGL program the
|
||||
tests hook instead of a game.
|
||||
- **Kill switch** — `hooking.kill_switch`, *Disable all hooking*: nothing is injected, whatever each game says.
|
||||
- **Ledger** — `ledger.db`, the SQLite file.
|
||||
- **Overlay** — `FrameLedger.Overlay.dll`, the component injected into a game. It draws nothing; the name is historical.
|
||||
- **`.partial`** — a session in progress, written in checksummed chunks so a crash leaves a usable prefix.
|
||||
- **Pre-scan** — the guard's check of a game when it is added, so the game's page can say what was found before it runs.
|
||||
- **Ring** — the single-producer, single-consumer queue of fixed-size frame records in shared memory.
|
||||
- **Safety unhook** — a finding during a session: the hook goes dormant and the session says so.
|
||||
- **Steady state** — the frame-generation state a session spent most of its time in, shown with its share.
|
||||
- **Tier 1 / Tier 2** — measured / recorded only. There is no third tier.
|
||||
- **Trial** — the first two hooked sessions under a user-mode exception; one that goes badly ends the exception for
|
||||
good.
|
||||
- **User-mode exception** — the one narrow exception to the guard's refusal, for anti-cheat that runs entirely in user
|
||||
mode ([`docs/19_SAFETY_AND_ANTICHEAT.md`](../docs/19_SAFETY_AND_ANTICHEAT.md)).
|
||||
- **Viewer** — the App started with `--data-dir` over a copy: no agent, nothing changed on the PC.
|
||||
- **WARP** — Windows' software renderer, which lets the hook harness run on CI without a GPU.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Developers
|
||||
|
||||
FrameLedger is a C++ component loaded into the games a user chose, a C# capture agent beside it, and a WPF app, with one
|
||||
SQLite file between them. These pages are short on purpose: each says what a part is and where its full document is.
|
||||
The full set is [`docs/`](../docs/README.md), and the rules every AI-assisted change follows are in
|
||||
[`CLAUDE.md`](../CLAUDE.md).
|
||||
|
||||
## Start here
|
||||
|
||||
1. [Contributor rules](Contributor-rules.md) — the rules every change keeps. Safety comes first, and some changes are
|
||||
refused whatever they improve.
|
||||
2. [Architecture](Architecture.md), then [Repository map](Repository-map.md).
|
||||
3. [Build and test](Build-and-test.md) — `./build.ps1 check` is the whole gate, the same one CI runs.
|
||||
|
||||
Picking up work where it stopped: [`docs/HANDOFF.md`](../docs/HANDOFF.md) has the sequencing, the owner's decisions
|
||||
and the traps that each cost a cycle.
|
||||
|
||||
## Where status lives
|
||||
|
||||
These pages never say what is done or what is next. Status is in four files, and nowhere else:
|
||||
|
||||
| Question | File |
|
||||
|---|---|
|
||||
| What is unresolved, and what does it block? | [`docs/20_OPEN_QUESTIONS.md`](../docs/20_OPEN_QUESTIONS.md) |
|
||||
| What was measured, and on what machine? | [`docs/spike-notes.md`](../docs/spike-notes.md) |
|
||||
| Which phase is where? | [`docs/15_ROADMAP.md`](../docs/15_ROADMAP.md) |
|
||||
| What landed, in which release? | [`CHANGELOG.md`](../CHANGELOG.md) |
|
||||
|
||||
Check a status claim against the code before you plan on it: more than one document has said "built" of something that
|
||||
was not, and the repository corrects such sentences where they stand — struck through and dated — rather than quietly.
|
||||
|
||||
## The other pages
|
||||
|
||||
- [Capture pipeline](Capture-pipeline.md) — what the agent does from the moment a game starts.
|
||||
- [Metrics](Metrics.md) — what each number means, and the rules for showing it.
|
||||
- [Data and IPC](Data-and-IPC.md) — the database, the shared memory and the pipe.
|
||||
- [App UI development](App-UI-development.md) — the WPF app, and the traps of its UI library.
|
||||
- [Releasing](Releasing.md) — from a merged change to an update on a user's PC.
|
||||
- [Developer glossary](Developer-glossary.md) — the project's own words.
|
||||
|
||||
Contributing is described in [`CONTRIBUTING.md`](../CONTRIBUTING.md), redistributing in [`FORKING.md`](../FORKING.md),
|
||||
and how to report a vulnerability in [`SECURITY.md`](../SECURITY.md).
|
||||
@@ -0,0 +1,43 @@
|
||||
# FrameLedger
|
||||
|
||||
**FrameLedger** records how your games run on this PC — frame rate and frame times, the settings a game really renders
|
||||
with, ray tracing, temperatures, and the game's own memory — and keeps every session so you can compare them later.
|
||||
Everything stays on your PC: no account, no telemetry. It is free software under the GNU GPL v3, for 64-bit Windows 10
|
||||
(22H2) and Windows 11, and it is in beta.
|
||||
|
||||
Download it from the [Releases page](https://github.com/poli0981/frameledger/releases).
|
||||
|
||||
## Use FrameLedger
|
||||
|
||||
The [user guide](../guide/README.md) is the one FrameLedger shows under Help ▸ User guide.
|
||||
|
||||
1. [Install and first start](../guide/01-install.md)
|
||||
2. [Record a game](../guide/02-record-a-game.md)
|
||||
3. [Read your results](../guide/03-read-your-results.md)
|
||||
4. [Anti-cheat and safety](../guide/04-anti-cheat-and-safety.md) — read it before you switch hooking on for any game
|
||||
5. [Your data](../guide/05-your-data.md)
|
||||
6. [Questions and answers](../guide/06-faq.md)
|
||||
|
||||
To look something up: [The screens](../guide/07-screens.md), [Every setting](../guide/08-settings.md),
|
||||
[When something goes wrong](../guide/09-troubleshooting.md), [Words FrameLedger uses](../guide/10-glossary.md),
|
||||
[The terms, in plain words](../guide/terms-in-plain-words.md), and [Limitations](../LIMITATIONS.md) — what FrameLedger
|
||||
cannot do.
|
||||
|
||||
## Build or change FrameLedger
|
||||
|
||||
Start at [Developers](Developers.md). The developer pages are short; each says what a part is and links to its full
|
||||
document in [`docs/`](../docs/README.md).
|
||||
|
||||
- [Architecture](Architecture.md) — the processes, and how a frame travels from the game to the screen.
|
||||
- [Repository map](Repository-map.md) — what is where.
|
||||
- [Build and test](Build-and-test.md) — the toolchain and the one gate.
|
||||
- [Contributor rules](Contributor-rules.md) — the rules every change keeps, safety first.
|
||||
- [Capture pipeline](Capture-pipeline.md), [Metrics](Metrics.md), [Data and IPC](Data-and-IPC.md),
|
||||
[App UI development](App-UI-development.md), [Releasing](Releasing.md), [Developer glossary](Developer-glossary.md).
|
||||
|
||||
## More
|
||||
|
||||
- A bug or a question: the project's [issues](https://github.com/poli0981/frameledger/issues). A game whose anti-cheat
|
||||
FrameLedger missed: the **Safety gap** form there.
|
||||
- A vulnerability: [`SECURITY.md`](../SECURITY.md).
|
||||
- The licence: [`LICENSE`](../LICENSE) (GPL v3) and [`NOTICE`](../NOTICE); the name: [`legal/TRADEMARKS.md`](../legal/TRADEMARKS.md).
|
||||
@@ -0,0 +1,38 @@
|
||||
# Metrics
|
||||
|
||||
How every number is computed is [`docs/03_METRICS.md`](../docs/03_METRICS.md) — the source of truth; the user's side is
|
||||
[Read your results](../guide/03-read-your-results.md). The calculators are in `src/FrameLedger.Domain/Metrics`, and the
|
||||
frame-generation ladder in `src/FrameLedger.Application/Recording`.
|
||||
|
||||
## The basics
|
||||
|
||||
- **Frame time** — present to present, timed with the performance counter at the moment the game presents, per swap
|
||||
chain. A paused or interrupted stretch is a gap, and gaps are left out of every figure.
|
||||
- **Average FPS** — frames divided by the time measured, never the mean of instantaneous rates.
|
||||
- **1% low / 0.1% low** — 1000 divided by the 99th / 99.9th percentile of the game's own frame times. They need at least
|
||||
1,000 / 10,000 frames; with fewer, N/A.
|
||||
- **Stutter** — a frame longer than twice the median of the 19 frames centred on it.
|
||||
|
||||
## The rules for showing a number
|
||||
|
||||
- **N/A means not measured.** Never 0, and never an estimate (`docs/02_SPEC.md`, FR-4.9).
|
||||
- **Frame generation is never folded into one number** (rule 6). Measured: `Native → Displayed (×N FG)`, for example
|
||||
`62 → 118 FPS (×1.9 FG)`. Not measured: **Presented FPS**, with a chip saying whether a frame-generation runtime was
|
||||
loaded — the word *Native* never stands alone. A session whose frame generation changed shows the state that lasted
|
||||
longest, always with its share: `×1.9 FG · 75%`.
|
||||
- **Ray tracing, path tracing, ray reconstruction** are Yes, No or N/A, each with where it came from (measured, the
|
||||
user's override, the game's default). Ray tracing is *Yes* on acceleration-structure builds or `DispatchRays`; *No*
|
||||
needs a capable device, the hook in place and no activity at all. Path tracing has no signature in the API, so it is
|
||||
only ever suggested.
|
||||
- **Tier 1 and Tier 2 are never averaged together.** A query and a chart split by tier; comparing across tiers asks the
|
||||
user first.
|
||||
|
||||
## The game's memory and the sensors
|
||||
|
||||
- The game's video memory and RAM are read from outside the game, as Task Manager shows them, once a second, in both
|
||||
tiers.
|
||||
- The PC's sensors come from three layers (Windows, LibreHardwareMonitor, NVAPI); what a layer cannot read is N/A.
|
||||
*GPU held back* exists on NVIDIA cards only. CPU temperature needs the agent elevated and PawnIO installed.
|
||||
|
||||
What is still unmeasured, or measured on one machine only, is in [`LIMITATIONS.md`](../LIMITATIONS.md) and
|
||||
[`legal/ACCURACY.md`](../legal/ACCURACY.md).
|
||||
@@ -0,0 +1,37 @@
|
||||
# Releasing
|
||||
|
||||
The full documents are [`docs/13_CI_CD.md`](../docs/13_CI_CD.md) and [`docs/11_UPDATER.md`](../docs/11_UPDATER.md).
|
||||
|
||||
## The workflows
|
||||
|
||||
| Workflow | Runs on | Does |
|
||||
|---|---|---|
|
||||
| `.github/workflows/ci.yml` | pushes to `main`, pull requests | `./build.ps1 check`, and on a pull request the changelog check. |
|
||||
| `.github/workflows/codeql.yml` | pushes and pull requests to `main`, weekly | CodeQL for C# and C++. |
|
||||
| `.github/workflows/rules-publish.yml` | a change to the detection rules or their validator | Fails when an anti-cheat entry is removed. |
|
||||
| `.github/workflows/release.yml` | a pushed `v*` tag; by hand, a rehearsal | Builds, gates and publishes a release. |
|
||||
| `.github/workflows/wiki.yml` | a successful release; by hand | Builds this wiki from `wiki/` and `guide/` and publishes it to the Wiki tab. |
|
||||
|
||||
## Cutting a release
|
||||
|
||||
1. One pull request moves the `[Unreleased]` entries of [`CHANGELOG.md`](../CHANGELOG.md) under a `## [x.y.z]` or
|
||||
`## [x.y.z-beta.N]` heading with an *Updating from* note, and updates the release lines in `README.md`, the accuracy
|
||||
statement (`legal/ACCURACY.md` and its copies) and `LIMITATIONS.md`. `VERSION` changes only with the numeric core.
|
||||
2. After it merges, a signed tag `vx.y.z` (or `vx.y.z-beta.N`) on the merge commit starts `release.yml`:
|
||||
- it checks the tag against `VERSION` and that the changelog has the section;
|
||||
- writes the release date into the legal documents;
|
||||
- runs the whole gate;
|
||||
- publishes the App and the agent (self-contained, ReadyToRun) and checks the published tree;
|
||||
- packs them with Velopack, with a delta from the previous release;
|
||||
- writes `SHA256SUMS.txt`;
|
||||
- creates the GitHub release from the changelog section, marked pre-release for a beta.
|
||||
3. The wiki follows: `wiki.yml` runs when the release run succeeds.
|
||||
4. Check the published assets against `SHA256SUMS.txt`, and the update feed.
|
||||
|
||||
Releases are not code-signed, so every release says so and publishes its checksums.
|
||||
|
||||
## How users get it
|
||||
|
||||
Velopack reads GitHub Releases. Settings ▸ Updates ▸ Channel is *Automatic* by default: a pre-release looks for
|
||||
pre-releases, a release for releases. A new version downloads in the background and installs only when FrameLedger
|
||||
restarts — never while a game is being recorded.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Repository map
|
||||
|
||||
The layout with its history is in [`CLAUDE.md`](../CLAUDE.md) §Solution layout.
|
||||
|
||||
## Managed code (`src/`, .NET 10, C#)
|
||||
|
||||
| Project | What it holds |
|
||||
|---|---|
|
||||
| `src/FrameLedger.Domain` | Entities and the metric calculators. References nothing. |
|
||||
| `src/FrameLedger.Application` | Use cases and ports: the capture loop, the session recorder, settings, the safety decisions. |
|
||||
| `src/FrameLedger.Infrastructure` | SQLite, the shared-memory reader, telemetry, the native interop, parsers. The **only** project that calls native code. |
|
||||
| `src/FrameLedger.Shared` | The pipe's message contracts and the C# mirror of the shared-memory structs. |
|
||||
| `src/FrameLedger.Agent` | The capture agent's host: the watcher, the pipe server, the recorder. |
|
||||
| `src/FrameLedger.App` | The WPF app (WPF UI 4.3.0): pages, dialogs, charts, strings in English, Vietnamese and Japanese. |
|
||||
| `src/FrameLedger.CaptureHost` | A developer tool, never shipped. |
|
||||
|
||||
Dependencies point inwards: App and Agent → Application → Domain; Infrastructure implements Application's ports.
|
||||
|
||||
## Native code (`src/native/`, C++20, MSVC)
|
||||
|
||||
| Folder | What it holds |
|
||||
|---|---|
|
||||
| `src/native/FrameLedger.Overlay` | The component loaded into a game: hooks, the ring writer. |
|
||||
| `src/native/FrameLedger.Injector` | The anti-cheat guard and injection, built into `FrameLedger.Guard.dll` for the agent. |
|
||||
| `src/native/FrameLedger.VkLayer` | The Vulkan implicit layer and its manifest. |
|
||||
| `src/native/FrameLedger.Shm` | The shared-memory layout, header-only; `fl_shm.h` is normative. |
|
||||
| `src/native/FrameLedger.NvapiBridge` | NVIDIA telemetry, loaded by the agent. |
|
||||
| `src/native/FrameLedger.ProcessStats` | The game's own memory, read from the agent. |
|
||||
| `src/native/tests` | The native test suites (ctest). |
|
||||
| `src/native/tools` | `hook-harness` (a dummy Direct3D 11/12, Vulkan and OpenGL app to hook), the probes, `fl-layout-dump`. |
|
||||
| `src/native/third_party` | Vendored vendor headers: NVAPI, Streamline, FidelityFX, Vulkan. |
|
||||
|
||||
## Everything else
|
||||
|
||||
| Path | What it holds |
|
||||
|---|---|
|
||||
| `tests/` | One test project per managed project, plus shared helpers and fixtures. |
|
||||
| `tools/` | The PowerShell gates and generators `./build.ps1` runs — see [Build and test](Build-and-test.md). |
|
||||
| `rules/detection-rules.json` | Engine, platform and capability signatures, and the anti-cheat blocklist. |
|
||||
| `guide/` | The user guide — embedded in the App, and the End-user half of this wiki. |
|
||||
| `wiki/` | This wiki's own pages, published to the Wiki tab when a release is made. |
|
||||
| `docs/` | The developer documents; [`docs/README.md`](../docs/README.md) is their index. |
|
||||
| `legal/` | The documents a user accepts, the accuracy statement, licences and notices. |
|
||||
| `.github/workflows/` | CI, CodeQL, the rules gate, the release and the wiki. |
|
||||
| `LIMITATIONS.md` | What the whole software cannot do, in a player's words; also in the App. |
|
||||
@@ -0,0 +1,31 @@
|
||||
**[Home](Home.md)**
|
||||
|
||||
**Use FrameLedger**
|
||||
|
||||
- [User guide](../guide/README.md)
|
||||
- [Install and first start](../guide/01-install.md)
|
||||
- [Record a game](../guide/02-record-a-game.md)
|
||||
- [Read your results](../guide/03-read-your-results.md)
|
||||
- [Anti-cheat and safety](../guide/04-anti-cheat-and-safety.md)
|
||||
- [Your data](../guide/05-your-data.md)
|
||||
- [Questions and answers](../guide/06-faq.md)
|
||||
- [The screens](../guide/07-screens.md)
|
||||
- [Every setting](../guide/08-settings.md)
|
||||
- [When something goes wrong](../guide/09-troubleshooting.md)
|
||||
- [Words FrameLedger uses](../guide/10-glossary.md)
|
||||
- [The terms, in plain words](../guide/terms-in-plain-words.md)
|
||||
- [Limitations](../LIMITATIONS.md)
|
||||
|
||||
**Build or change FrameLedger**
|
||||
|
||||
- [Developers](Developers.md)
|
||||
- [Architecture](Architecture.md)
|
||||
- [Repository map](Repository-map.md)
|
||||
- [Build and test](Build-and-test.md)
|
||||
- [Contributor rules](Contributor-rules.md)
|
||||
- [Capture pipeline](Capture-pipeline.md)
|
||||
- [Metrics](Metrics.md)
|
||||
- [Data and IPC](Data-and-IPC.md)
|
||||
- [App UI development](App-UI-development.md)
|
||||
- [Releasing](Releasing.md)
|
||||
- [Developer glossary](Developer-glossary.md)
|
||||
Reference in new issue
Block a user