diff --git a/.gitattributes b/.gitattributes index 556df6245a..516ccee298 100644 --- a/.gitattributes +++ b/.gitattributes @@ -57,6 +57,9 @@ apple/TablePro/Resources/ThirdPartyLicenses/texts/** linguist-vendored # Joins the SQLite copyright page and the source blessing with a sentence of its own. apple/TablePro/Resources/ThirdPartyLicenses/texts/sqlite.txt -linguist-vendored +# The feature parity table, written from features.yml beside it by scripts/feature-parity.py +docs/feature-parity/README.md linguist-generated + # Generated Rust and Linux files (Cargo, cargo-about, license_metadata.py) Cargo.lock linguist-generated linux/data/licenses/** linguist-generated diff --git a/.github/workflows/ci-lint.yml b/.github/workflows/ci-lint.yml index 407080ccf9..984767134b 100644 --- a/.github/workflows/ci-lint.yml +++ b/.github/workflows/ci-lint.yml @@ -121,6 +121,9 @@ jobs: title="$(gh api "repos/$REPOSITORY/pulls/$PR_NUMBER" --jq .title)" scripts/ci/check-changelog-edits.sh "$(git rev-parse HEAD^1)" "$title" + - name: Check docs/feature-parity/README.md matches features.yml + run: python3 scripts/feature-parity.py --check + # shellcheck cannot tell a library function from a command, so a missing source is exit 127 # at release time (v0.67.1). - name: Check every script sources the libraries it calls into diff --git a/AGENTS.md b/AGENTS.md index 8ef7bc03ad..f1998c60f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,7 @@ Native database clients with a native UI per platform: `apple/` holds the macOS - `core/`: the shared Rust core's crates, its architecture and its cross-platform decisions. `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml`, `rustfmt.toml`, `clippy.toml`, `deny.toml` and `.config/nextest.toml` at the top are its Cargo workspace, which also holds the Linux app's crates. - `.github/`: workflows, actions, the PR template and `plugin-registry.json`. - `.claude/`: the path-scoped rules and the `fix-issue` and `release` skills, which Codex sees through `.agents/skills/`. +- `docs/feature-parity/`: which of the macOS app's features the Linux and Windows apps have. `scripts/feature-parity.py` writes its `README.md` from `features.yml`. A pull request that brings a listed feature to Linux or Windows updates its row. - `scripts/`: `banned-words.txt` with `check-banned-words.sh`, the PR title and changed-path checks in `scripts/ci`, and the towncrier pin in `scripts/release`. - `appcast.xml`: the legacy feed apps up to 0.81 read from `main` (`apple/RELEASING.md`, Channels). - `.oss-scanner/`: the build image and threat model for Anthropic's OSS Scanner. Renaming a TableProCore target that `.oss-scanner/swift/Package.swift` lists updates it there too. diff --git a/docs/feature-parity/README.md b/docs/feature-parity/README.md new file mode 100644 index 0000000000..e1b845b486 --- /dev/null +++ b/docs/feature-parity/README.md @@ -0,0 +1,134 @@ +# Feature parity + +Which of the macOS app's features the Linux and Windows apps have. A feature with no row has not been compared yet. +What the Linux app does in each area, in detail: [linux/ROADMAP.md](../../linux/ROADMAP.md#implemented). + +`scripts/feature-parity.py` writes this file from [features.yml](features.yml). Edit that file, then run the script. + +| Status | Meaning | +|---|---| +| Yes | On `main`. | +| In #N | In that open pull request. | +| Partial | Part of it is on `main`. The note says which part. | +| No | Not built. | +| n/a | Does not apply to that app. The note says why. | +| Unknown | Not checked yet. | + +## Connections + +| Feature | Linux | Windows | +|---|---|---| +| Saved connections, groups, favorites and tags | Yes | Yes | +| SSH tunnels with jump hosts | Yes | Partial: no jump hosts | +| Safe Mode per connection (off, confirm writes, read only) | Yes | Partial: Confirm Writes does not ask before a write | +| Import connections from other apps | Yes | No: imports a TablePro JSON file only | +| Application menu with Quit | Yes: a main menu, since GNOME apps have no menu bar, and a session menu for the database commands | Yes | +| The server's other databases in the sidebar | Yes: each opened from the sidebar's menu | No | + +## Sidebar + +| Feature | Linux | Windows | +|---|---|---| +| Schemas and tables, with search | Yes | Yes | +| A schema's objects grouped by kind | Yes | Yes | +| Width set by dragging its edge | Yes | Yes | +| Toggle in the window header | Yes | Partial: View > Object Tree and Ctrl+B; no button in the title bar | +| Bottom bar with an Add menu | Yes | No | +| Choose which schemas the sidebar lists | Yes | No | +| Tables and Favorites scope switch | Yes | No | +| Favorite folders | Yes | No | +| Favorite keywords that expand in the editor | No | No | +| Favorite tables and databases, with environments | No | No | +| Open Quickly (find a table by name) | Yes: tables, views, saved queries and past queries | Partial: Ctrl+P moves to the sidebar's filter | + +## Data grid + +| Feature | Linux | Windows | +|---|---|---| +| Virtualized grid with paging and an exact or estimated count | Yes | Yes | +| Alternate row shading | Yes | No | +| Values in the monospace font | Yes | No | +| Row numbers stay in view while scrolling sideways | Yes | Yes | +| Inline cell editing with pending changes, undo and redo | Yes | No | +| Filters per column and as a WHERE fragment | Yes | No | +| Open a referenced row and the rows that reference one | Yes | No | +| Set Value on every selected row (Empty, NULL, DEFAULT, UUID, an expression, any value) | Partial: Empty, NULL, DEFAULT and the engine's expressions | No | +| Show row numbers, row height and the text shown for NULL | Yes | No | +| Highlight rules (color rows and cells by a condition) | Yes | No | +| The grid in the editor theme's colors | Yes | No | +| Font of the grid's cells, and zoom | Partial: family and size; no zoom | No | +| Date format of the cells | Yes | No | +| Default sort of a table (none, primary key, first column) | Yes | No | +| The format Copy writes for several rows | Yes | No: copies tab-separated values only | +| Open the row details when a row is selected | Yes | No | +| Mark zero-width, control and special space characters in the value editor | Yes | No | + +## Bottom bar + +| Feature | Linux | Windows | +|---|---|---| +| Columns button | Yes | No | +| Time a page or a query took | Yes | Yes | +| Data and Structure in one tab | Yes | No | +| JSON view of the rows | Partial: table tabs; not query results | No | +| Chart view of a result | No | No | +| Map view of a result | No | No | + +## Row details + +| Feature | Linux | Windows | +|---|---|---| +| Row details pane | Yes | No | +| Type, key and edit marks on a field | Yes | No | +| Foreign key mark on a field | Yes | No | +| Field search and an edited-only filter | Yes | No | +| A field drawn as its name over its value | Yes | No | +| An editor inside each field row | Yes | No | +| A menu on each field | Yes | No | +| A row as JSON | Partial: a dialog from the grid's menu, not a view of the row details | No | + +## SQL editor + +| Feature | Linux | Windows | +|---|---|---| +| Highlighting, completion, snippets and formatting | Yes | Partial: highlighting only | +| Move a query tab to another database | Yes | No | +| Color schemes | Yes | No | +| Vim keybindings | Yes | No | + +## Structure and schema + +| Feature | Linux | Windows | +|---|---|---| +| Structure editor with a reviewed ALTER | Yes | No | +| ER diagram | Yes | No | + +## History, import and export + +| Feature | Linux | Windows | +|---|---|---| +| Query history with search, pins and export | Yes | No | +| Saved queries | Yes | No | +| Export results (CSV, JSON, Markdown, HTML, XML, Excel, SQL) | Yes | No | +| Export a database as SQL and import a SQL file | Yes | No | + +## Assistant, MCP, account and command line + +| Feature | Linux | Windows | +|---|---|---| +| AI assistant | Yes | No | +| MCP server for outside clients | Yes | No | +| TablePro account and entitlement | Yes | No | +| The `tablepro` command line tool | Yes | No: `tablepro.exe` opens the app and reads no arguments | + +## Window toolbar + +| Feature | Linux | Windows | +|---|---|---| +| Safe Mode level in the toolbar | Yes | No | +| Refresh button | Yes | Yes | +| Save Changes button | Yes | No | +| Connection and database chips | Partial: the title names the connection and the sidebar lists every open connection and database; no chips | Partial: the title bar names the connection; no database chip | +| Back and Forward through a tab's browse history | n/a: a referenced row opens in a new tab, where macOS moves the tab to it | No | +| Actions menu (Preview SQL, Show and Copy DDL, Users and Roles, Query Insights, Server Dashboard) | Partial: Show CREATE TABLE is in the sidebar's menu; the rest is not built | No | +| Reconnect after a lost connection | Yes | Yes | diff --git a/docs/feature-parity/features.yml b/docs/feature-parity/features.yml new file mode 100644 index 0000000000..504a6b430a --- /dev/null +++ b/docs/feature-parity/features.yml @@ -0,0 +1,240 @@ +# The rows of README.md, which scripts/feature-parity.py writes from this file. README.md explains +# the statuses. A value is a status, or a mapping of status, pr and note. + +areas: + - name: Connections + features: + - name: Saved connections, groups, favorites and tags + linux: yes + windows: yes + - name: SSH tunnels with jump hosts + linux: yes + windows: {status: partial, note: "no jump hosts"} + - name: Safe Mode per connection (off, confirm writes, read only) + linux: yes + windows: {status: partial, note: "Confirm Writes does not ask before a write"} + - name: Import connections from other apps + linux: yes + windows: {status: no, note: "imports a TablePro JSON file only"} + - name: Application menu with Quit + linux: {status: yes, note: "a main menu, since GNOME apps have no menu bar, and a session menu for the database commands"} + windows: yes + - name: The server's other databases in the sidebar + linux: {status: yes, note: "each opened from the sidebar's menu"} + windows: no + + - name: Sidebar + features: + - name: Schemas and tables, with search + linux: yes + windows: yes + - name: A schema's objects grouped by kind + linux: yes + windows: yes + - name: Width set by dragging its edge + linux: yes + windows: yes + - name: Toggle in the window header + linux: yes + windows: {status: partial, note: "View > Object Tree and Ctrl+B; no button in the title bar"} + - name: Bottom bar with an Add menu + linux: yes + windows: no + - name: Choose which schemas the sidebar lists + linux: yes + windows: no + - name: Tables and Favorites scope switch + linux: yes + windows: no + - name: Favorite folders + linux: yes + windows: no + - name: Favorite keywords that expand in the editor + linux: no + windows: no + - name: Favorite tables and databases, with environments + linux: no + windows: no + - name: Open Quickly (find a table by name) + linux: {status: yes, note: "tables, views, saved queries and past queries"} + windows: {status: partial, note: "Ctrl+P moves to the sidebar's filter"} + + - name: Data grid + features: + - name: Virtualized grid with paging and an exact or estimated count + linux: yes + windows: yes + - name: Alternate row shading + linux: yes + windows: no + - name: Values in the monospace font + linux: yes + windows: no + - name: Row numbers stay in view while scrolling sideways + linux: yes + windows: yes + - name: Inline cell editing with pending changes, undo and redo + linux: yes + windows: no + - name: Filters per column and as a WHERE fragment + linux: yes + windows: no + - name: Open a referenced row and the rows that reference one + linux: yes + windows: no + - name: Set Value on every selected row (Empty, NULL, DEFAULT, UUID, an expression, any value) + linux: {status: partial, note: "Empty, NULL, DEFAULT and the engine's expressions"} + windows: no + - name: Show row numbers, row height and the text shown for NULL + linux: yes + windows: no + - name: Highlight rules (color rows and cells by a condition) + linux: yes + windows: no + - name: The grid in the editor theme's colors + linux: yes + windows: no + - name: Font of the grid's cells, and zoom + linux: {status: partial, note: "family and size; no zoom"} + windows: no + - name: Date format of the cells + linux: yes + windows: no + - name: Default sort of a table (none, primary key, first column) + linux: yes + windows: no + - name: The format Copy writes for several rows + linux: yes + windows: {status: no, note: "copies tab-separated values only"} + - name: Open the row details when a row is selected + linux: yes + windows: no + - name: Mark zero-width, control and special space characters in the value editor + linux: yes + windows: no + + - name: Bottom bar + features: + - name: Columns button + linux: yes + windows: no + - name: Time a page or a query took + linux: yes + windows: yes + - name: Data and Structure in one tab + linux: yes + windows: no + - name: JSON view of the rows + linux: {status: partial, note: "table tabs; not query results"} + windows: no + - name: Chart view of a result + linux: no + windows: no + - name: Map view of a result + linux: no + windows: no + + - name: Row details + features: + - name: Row details pane + linux: yes + windows: no + - name: Type, key and edit marks on a field + linux: yes + windows: no + - name: Foreign key mark on a field + linux: yes + windows: no + - name: Field search and an edited-only filter + linux: yes + windows: no + - name: A field drawn as its name over its value + linux: yes + windows: no + - name: An editor inside each field row + linux: yes + windows: no + - name: A menu on each field + linux: yes + windows: no + - name: A row as JSON + linux: {status: partial, note: "a dialog from the grid's menu, not a view of the row details"} + windows: no + + - name: SQL editor + features: + - name: Highlighting, completion, snippets and formatting + linux: yes + windows: {status: partial, note: "highlighting only"} + - name: Move a query tab to another database + linux: yes + windows: no + - name: Color schemes + linux: yes + windows: no + - name: Vim keybindings + linux: yes + windows: no + + - name: Structure and schema + features: + - name: Structure editor with a reviewed ALTER + linux: yes + windows: no + - name: ER diagram + linux: yes + windows: no + + - name: History, import and export + features: + - name: Query history with search, pins and export + linux: yes + windows: no + - name: Saved queries + linux: yes + windows: no + - name: Export results (CSV, JSON, Markdown, HTML, XML, Excel, SQL) + linux: yes + windows: no + - name: Export a database as SQL and import a SQL file + linux: yes + windows: no + + - name: Assistant, MCP, account and command line + features: + - name: AI assistant + linux: yes + windows: no + - name: MCP server for outside clients + linux: yes + windows: no + - name: TablePro account and entitlement + linux: yes + windows: no + - name: The `tablepro` command line tool + linux: yes + windows: {status: no, note: "`tablepro.exe` opens the app and reads no arguments"} + + - name: Window toolbar + features: + - name: Safe Mode level in the toolbar + linux: yes + windows: no + - name: Refresh button + linux: yes + windows: yes + - name: Save Changes button + linux: yes + windows: no + - name: Connection and database chips + linux: {status: partial, note: "the title names the connection and the sidebar lists every open connection and database; no chips"} + windows: {status: partial, note: "the title bar names the connection; no database chip"} + - name: Back and Forward through a tab's browse history + linux: {status: na, note: "a referenced row opens in a new tab, where macOS moves the tab to it"} + windows: no + - name: Actions menu (Preview SQL, Show and Copy DDL, Users and Roles, Query Insights, Server Dashboard) + linux: {status: partial, note: "Show CREATE TABLE is in the sidebar's menu; the rest is not built"} + windows: no + - name: Reconnect after a lost connection + linux: yes + windows: yes diff --git a/linux/ROADMAP.md b/linux/ROADMAP.md index 1e3f1694fb..160304c6d6 100644 --- a/linux/ROADMAP.md +++ b/linux/ROADMAP.md @@ -183,7 +183,7 @@ The app runs on GNOME 50 ([ADR 0015](docs/decisions/0015-gnome-50-platform-floor ## Backlog -Remaining work and known issues, in no order. +Remaining work and known issues, in no order. The macOS app's features this app lacks are in the [feature parity table](../docs/feature-parity/README.md). ### Connections diff --git a/scripts/ci/test_feature_parity.py b/scripts/ci/test_feature_parity.py new file mode 100644 index 0000000000..e8c6f67382 --- /dev/null +++ b/scripts/ci/test_feature_parity.py @@ -0,0 +1,96 @@ +#!/usr/bin/env python3 + +import importlib.util +import tempfile +import unittest +from pathlib import Path + +SCRIPT = Path(__file__).resolve().parent.parent / "feature-parity.py" +SPEC = importlib.util.spec_from_file_location("feature_parity", SCRIPT) +parity = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(parity) + + +def registry(*rows): + features = "".join( + f" - name: {name}\n linux: {linux}\n windows: {windows}\n" for name, linux, windows in rows + ) + return f"areas:\n - name: Area\n features:\n{features}" + + +def load(text): + with tempfile.TemporaryDirectory() as folder: + path = Path(folder) / "features.yml" + path.write_text(text, encoding="utf-8") + return parity.load(path) + + +def rendered(text): + return parity.render(load(text)) + + +class LoadTests(unittest.TestCase): + def test_yes_and_no_stay_statuses(self): + [(_, [(_, cells)])] = load(registry(("A feature", "yes", "no"))) + self.assertEqual(cells, [("yes", None, None), ("no", None, None)]) + + def test_a_pending_feature_names_its_pull_request(self): + with self.assertRaisesRegex(parity.RegistryError, "pr names"): + load(registry(("A feature", "pending", "unknown"))) + + def test_only_a_pending_feature_names_a_pull_request(self): + with self.assertRaisesRegex(parity.RegistryError, "pr names"): + load(registry(("A feature", "{status: yes, pr: 4121}", "unknown"))) + + def test_a_pull_request_is_a_number(self): + with self.assertRaisesRegex(parity.RegistryError, "not a pull request number"): + load(registry(("A feature", "{status: pending, pr: soon}", "unknown"))) + + def test_a_partial_or_na_feature_says_why(self): + for status in ("partial", "na"): + with self.subTest(status=status), self.assertRaisesRegex(parity.RegistryError, "says why"): + load(registry(("A feature", status, "unknown"))) + + def test_an_unknown_status_is_refused(self): + with self.assertRaisesRegex(parity.RegistryError, "is not one of"): + load(registry(("A feature", "done", "unknown"))) + + def test_a_feature_names_both_apps_and_nothing_else(self): + missing = "areas:\n - name: Area\n features:\n - name: A feature\n linux: yes\n" + with self.assertRaisesRegex(parity.RegistryError, "exactly"): + load(missing) + with self.assertRaisesRegex(parity.RegistryError, "exactly"): + load(registry(("A feature", "yes", "yes")) + " macos: yes\n") + + def test_a_feature_is_listed_once(self): + with self.assertRaisesRegex(parity.RegistryError, "listed twice"): + load(registry(("A feature", "yes", "yes"), ("A feature", "no", "no"))) + + def test_a_note_is_one_line(self): + text = registry(("A feature", "{status: partial, note: x}", "unknown")).replace("note: x", 'note: "a\\nb"') + with self.assertRaisesRegex(parity.RegistryError, "one line"): + load(text) + + +class RenderTests(unittest.TestCase): + def test_a_pending_feature_links_its_pull_request(self): + text = rendered(registry(("A feature", "{status: pending, pr: 4121}", "unknown"))) + self.assertIn("| A feature | In [#4121](https://github.com/TableProApp/TablePro/pull/4121) | Unknown |", text) + + def test_a_note_follows_the_status_and_links_its_pull_requests(self): + text = rendered(registry(("A feature", '{status: partial, note: "tables only, views in #4133"}', "no"))) + link = "[#4133](https://github.com/TableProApp/TablePro/pull/4133)" + self.assertIn(f"| A feature | Partial: tables only, views in {link} | No |", text) + + def test_a_pipe_does_not_end_the_cell(self): + text = rendered(registry(("A feature", "{status: na, note: 'a | b'}", "yes"))) + self.assertIn("| n/a: a \\| b | Yes |", text) + + def test_every_status_is_in_the_legend(self): + text = rendered(registry(("A feature", "yes", "yes"))) + for label, meaning in parity.STATUSES.values(): + self.assertIn(f"| {label} | {meaning} |", text) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/feature-parity.py b/scripts/feature-parity.py new file mode 100755 index 0000000000..98a8b69298 --- /dev/null +++ b/scripts/feature-parity.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +"""Write docs/feature-parity/README.md from docs/feature-parity/features.yml. + +Usage: + scripts/feature-parity.py write README.md + scripts/feature-parity.py --check fail when features.yml is invalid or README.md is not what it writes +""" + +import argparse +import re +import sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +SOURCE = ROOT / "docs" / "feature-parity" / "features.yml" +TARGET = SOURCE.with_name("README.md") +PULL = "https://github.com/TableProApp/TablePro/pull/" + +PLATFORMS = (("linux", "Linux"), ("windows", "Windows")) +STATUSES = { + "yes": ("Yes", "On `main`."), + "pending": ("In #N", "In that open pull request."), + "partial": ("Partial", "Part of it is on `main`. The note says which part."), + "no": ("No", "Not built."), + "na": ("n/a", "Does not apply to that app. The note says why."), + "unknown": ("Unknown", "Not checked yet."), +} +NEEDS_NOTE = {"partial", "na"} +NUMBER = re.compile(r"[1-9][0-9]*") +REFERENCE = re.compile(r"#([1-9][0-9]*)\b") + +HEADER = """# Feature parity + +Which of the macOS app's features the Linux and Windows apps have. A feature with no row has not been compared yet. +What the Linux app does in each area, in detail: [linux/ROADMAP.md](../../linux/ROADMAP.md#implemented). + +`scripts/feature-parity.py` writes this file from [features.yml](features.yml). Edit that file, then run the script. + +| Status | Meaning | +|---|---| +""" + + +class RegistryError(ValueError): + pass + + +def one_line(text, where, what): + if not isinstance(text, str) or not text.strip() or "\n" in text: + raise RegistryError(f"{where}: {what} is one line of text") + return text.strip() + + +def cell(value, where): + if isinstance(value, str): + value = {"status": value} + if not isinstance(value, dict): + raise RegistryError(f"{where}: give a status, or a mapping of status, pr and note") + extra = sorted(set(value) - {"status", "pr", "note"}) + if extra: + raise RegistryError(f"{where}: unknown keys {', '.join(extra)}") + status, pr, note = value.get("status"), value.get("pr"), value.get("note") + if status not in STATUSES: + raise RegistryError(f"{where}: status {status!r} is not one of {', '.join(STATUSES)}") + if (status == "pending") != (pr is not None): + raise RegistryError(f"{where}: pr names the open pull request of a pending feature, and only of one") + if pr is not None and not (isinstance(pr, str) and NUMBER.fullmatch(pr)): + raise RegistryError(f"{where}: pr {pr!r} is not a pull request number") + if note is not None: + note = one_line(note, where, "note") + elif status in NEEDS_NOTE: + raise RegistryError(f"{where}: a {status} feature says why in a note") + return status, pr, note + + +def load(path): + # BaseLoader keeps every scalar a string, so yes and no stay statuses instead of YAML 1.1 booleans. + with Path(path).open(encoding="utf-8") as handle: + document = yaml.load(handle, Loader=yaml.BaseLoader) + areas = document.get("areas") if isinstance(document, dict) else None + if not isinstance(areas, list) or not areas: + raise RegistryError("give a list of areas") + names = set() + loaded = [] + for area in areas: + if not isinstance(area, dict) or set(area) != {"name", "features"}: + raise RegistryError("an area has a name and features, and nothing else") + title = one_line(area["name"], "area", "name") + if not isinstance(area["features"], list) or not area["features"]: + raise RegistryError(f"{title}: give a list of features") + features = [] + for feature in area["features"]: + expected = {"name"} | {key for key, _ in PLATFORMS} + if not isinstance(feature, dict) or set(feature) != expected: + raise RegistryError(f"{title}: a feature has exactly {', '.join(sorted(expected))}") + name = one_line(feature["name"], title, "name") + if name in names: + raise RegistryError(f"{name}: listed twice") + names.add(name) + cells = [cell(feature[key], f"{name}, {key}") for key, _ in PLATFORMS] + features.append((name, cells)) + loaded.append((title, features)) + return loaded + + +def linked(text): + return REFERENCE.sub(lambda match: f"[#{match[1]}]({PULL}{match[1]})", text.replace("|", "\\|")) + + +def shown(status, pr, note): + text = f"In [#{pr}]({PULL}{pr})" if status == "pending" else STATUSES[status][0] + return f"{text}: {linked(note)}" if note else text + + +def render(areas): + lines = [HEADER.rstrip("\n")] + lines += [f"| {label} | {meaning} |" for label, meaning in STATUSES.values()] + header = "| Feature | " + " | ".join(label for _, label in PLATFORMS) + " |" + for title, features in areas: + lines += ["", f"## {title}", "", header, "|---" * (len(PLATFORMS) + 1) + "|"] + for name, cells in features: + lines.append("| " + " | ".join([linked(name)] + [shown(*value) for value in cells]) + " |") + return "\n".join(lines) + "\n" + + +def main(argv=None): + parser = argparse.ArgumentParser(description="Write docs/feature-parity/README.md from features.yml.") + parser.add_argument("--check", action="store_true", help="fail when README.md is not what features.yml writes") + arguments = parser.parse_args(argv) + try: + text = render(load(SOURCE)) + except (OSError, yaml.YAMLError, RegistryError) as error: + print(f"{SOURCE.relative_to(ROOT)}: {error}", file=sys.stderr) + return 1 + if not arguments.check: + TARGET.write_text(text, encoding="utf-8") + return 0 + if not TARGET.is_file() or TARGET.read_text(encoding="utf-8") != text: + print(f"{TARGET.relative_to(ROOT)} is stale. Run scripts/feature-parity.py", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main())