src-auth-perms-sync 0.3.1__tar.gz → 0.5.0__tar.gz

{src_auth_perms_sync-0.3.1 → src_auth_perms_sync-0.5.0}/.gitignore

@@ -12,6 +12,7 @@ __pycache__
 *.py[cod]
 *.py[oc]
 *.swp
+*.tsv
 *.yaml
 build/
 dist/
@@ -24,3 +25,4 @@ wheels/
 !.env.example
 !.markdownlint-cli2.yaml
 !maps-example.yaml
+!tests/**/*.yaml

{src_auth_perms_sync-0.3.1 → src_auth_perms_sync-0.5.0}/AGENTS.md

@@ -1,5 +1,10 @@
 # AGENTS.md
 
+## Reference materials
+
+- GraphQL schema and database migrations (changes to SQL schema) are available in
+  <https://github.com/sourcegraph/artifacts>
+
 ## Linting
 
 ```bash
@@ -26,21 +31,40 @@ uv run src-auth-perms-sync --help
 
 ## Testing
 
-- First run a dry-run (default behaviour, without `--apply` flag) against a Sourcegraph instance
+All testing runs through one entrypoint: `tests/run.py`. Output goes to the
+console and to a per-run log file under `logs/`. Each level runs only its
+own checks.
 
 ```bash
-uv run src-auth-perms-sync [--get]
-uv run src-auth-perms-sync --set maps.yaml --full
-uv run src-auth-perms-sync --restore backups/<source>/<run>/before.json
+# Fast, no network (also what the pre-commit hook runs):
+# lint, format, pyright, unit + fixture tests, CLI rejection matrix,
+# randomized permission invariants
+uv run tests/run.py
+
+# End-to-end runs against the .env test instance with independent GraphQL
+# read-back verification, and a wheel install smoke test
+uv run tests/run.py --live
+
+# Run a subset: comma-delimited test names, substring match
+uv run tests/run.py --live full-overwrite-unions
+uv run tests/run.py --live wheel,baseline
+
+# Repeated timed runs with Jaeger trace retention, RSS sampling,
+# optional kubectl load monitoring, and baseline comparison
+uv run tests/run.py --performance --repeat 3
+uv run tests/run.py --performance --baseline-command "uvx src-auth-perms-sync@latest" \
+  --fail-on-memory-regression-percent 10
+
+# Regenerate fixture goldens after editing tests/e2e/fixtures/ cases
+uv run tests/run.py --update-golden
 ```
 
-- Read the output, and evaluate the expected changes
-- If the expected changes look correct
-  - Run with the `--apply` flag against the test instance
-  - Read and evaluate the output for expected changes
-  - Run with the `--restore` flag against the test instance
-  - Always inspect the before / after snapshots in
-    `src-auth-perms-sync-runs/<endpoint>/backups/` afterward to confirm the diff matches what you expected
+- Fixture cases live in `tests/e2e/fixtures/<case>/` — see the README there
+  for the format. Add cases there to cover new mapping behaviors.
+- For manual verification against a real instance, dry-run first (no
+  `--apply`), read the planned changes, then `--apply` on a scratch instance
+  and inspect the before/after snapshots under
+  `src-auth-perms-sync-runs/<endpoint>/runs/`.
 
 ## Release process
 
@@ -177,10 +201,16 @@ organization sync maps SAML groups to Sourcegraph org membership. Read
 CLI lives in `src/src_auth_perms_sync/`; invoke with `uv run src-auth-perms-sync`.
 Strict pyright covers the package. Root modules are entrypoints only:
 
-- `cli.py` — `main()`, arg parsing, owns the CLI description.
+- `cli.py` — `main()`, arg parsing, owns the CLI description. Module
+  wrappers (`Get`/`Set`/`Restore`/`SyncSamlOrgs`) return result dataclasses
+  and never install logging handlers; only `main()` runs CLI-mode logging.
 - `shared/` — cross-workflow helpers: Sourcegraph auth-provider/user list
   helpers, shared GraphQL operations and TypedDicts, site-config validation,
-  and SAML group parsing.
+  and SAML group parsing. `shared/backups.py` defines `RunPaths`: every
+  filesystem path for one run, resolved once at the edge
+  (`resolve_run_paths`) and threaded explicitly — never recompute paths
+  from cwd or globals below the edge, and honor `run_paths.write_files`
+  (False under `--no-files`) before any disk write.
 
 Business workflows live in packages:
 

{src_auth_perms_sync-0.3.1 → src_auth_perms_sync-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-auth-perms-sync
-Version: 0.3.1
+Version: 0.5.0
 Summary: Set Sourcegraph permissions from authentication provider data
 Project-URL: Homepage, https://github.com/sourcegraph/src-auth-perms-sync
 Project-URL: Issues, https://github.com/sourcegraph/src-auth-perms-sync/issues
@@ -18,7 +18,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: json5>=0.14.0
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: src-py-lib[otel]==0.2.1
+Requires-Dist: src-py-lib[otel]==0.3.0
 Description-Content-Type: text/markdown
 
 # src-auth-perms-sync
@@ -160,14 +160,44 @@ config = src.Config(
     apply=False,  # Dry run (default), set to True to make changes
 )
 
-succeeded = src.Set(config)
+result = src.Set(config)  # truthy on success; result.paths has run artifacts
+
+# Discovery returns the auth provider and code host data in memory, so you
+# can assemble mapping rules without re-parsing the generated YAML files:
+get_result = src.Get(config)
+for provider in get_result.auth_providers:
+    ...
+for code_host in get_result.code_hosts:
+    ...
 
 # Other command wrappers:
-# succeeded = src.Get(config)
-# succeeded = src.Restore(config)
-# succeeded = src.SyncSamlOrgs(config)
+# result = src.Restore(config)
+# result = src.SyncSamlOrgs(config)
+```
+
+Module mode never touches your `logging` handlers or the root logger — your
+application's logging config stays in charge. To see progress messages:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)  # or your own handlers
+logging.getLogger("src_auth_perms_sync").setLevel(logging.INFO)
+logging.getLogger("src_py_lib").setLevel(logging.INFO)
 ```
 
+To receive structured wide events programmatically, pass an event sink:
+
+```python
+events = src.InMemoryEventSink()
+src.Get(config, event_sink=events)   # or src.CallbackEventSink(my_function)
+```
+
+To run fully disk-free (no generated YAML, snapshots, or log file), set
+`no_files=True`. Combined with `apply=True` this also requires
+`no_backup=True`, because skipping files gives up the before/after
+snapshots that make `--apply` reversible.
+
 ## Inputs
 
 - Environment variables (CLI), or src.Config args (Python import)
@@ -177,7 +207,12 @@ succeeded = src.Set(config)
 
 - YAML maps file
   - By default: `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
-  - Or pass `--maps-path ./path/to/maps.yaml`
+  - Or pass `--maps-path ./path/to/maps.yaml` (works for both `get` and `set`,
+    so the maps file can live outside the generated artifacts tree)
+  - `--artifacts-dir DIR` moves the whole artifacts tree (generated YAML,
+    snapshots, logs); the default is `./src-auth-perms-sync-runs`
+  - `--no-files` writes nothing to disk; with `--apply` it also requires
+    `--no-backup`
   - A list of mapping rules
   - Each mapping rule takes
     - A map of filters for users

{src_auth_perms_sync-0.3.1 → src_auth_perms_sync-0.5.0}/README.md

@@ -137,14 +137,44 @@ config = src.Config(
     apply=False,  # Dry run (default), set to True to make changes
 )
 
-succeeded = src.Set(config)
+result = src.Set(config)  # truthy on success; result.paths has run artifacts
+
+# Discovery returns the auth provider and code host data in memory, so you
+# can assemble mapping rules without re-parsing the generated YAML files:
+get_result = src.Get(config)
+for provider in get_result.auth_providers:
+    ...
+for code_host in get_result.code_hosts:
+    ...
 
 # Other command wrappers:
-# succeeded = src.Get(config)
-# succeeded = src.Restore(config)
-# succeeded = src.SyncSamlOrgs(config)
+# result = src.Restore(config)
+# result = src.SyncSamlOrgs(config)
+```
+
+Module mode never touches your `logging` handlers or the root logger — your
+application's logging config stays in charge. To see progress messages:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)  # or your own handlers
+logging.getLogger("src_auth_perms_sync").setLevel(logging.INFO)
+logging.getLogger("src_py_lib").setLevel(logging.INFO)
 ```
 
+To receive structured wide events programmatically, pass an event sink:
+
+```python
+events = src.InMemoryEventSink()
+src.Get(config, event_sink=events)   # or src.CallbackEventSink(my_function)
+```
+
+To run fully disk-free (no generated YAML, snapshots, or log file), set
+`no_files=True`. Combined with `apply=True` this also requires
+`no_backup=True`, because skipping files gives up the before/after
+snapshots that make `--apply` reversible.
+
 ## Inputs
 
 - Environment variables (CLI), or src.Config args (Python import)
@@ -154,7 +184,12 @@ succeeded = src.Set(config)
 
 - YAML maps file
   - By default: `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
-  - Or pass `--maps-path ./path/to/maps.yaml`
+  - Or pass `--maps-path ./path/to/maps.yaml` (works for both `get` and `set`,
+    so the maps file can live outside the generated artifacts tree)
+  - `--artifacts-dir DIR` moves the whole artifacts tree (generated YAML,
+    snapshots, logs); the default is `./src-auth-perms-sync-runs`
+  - `--no-files` writes nothing to disk; with `--apply` it also requires
+    `--no-backup`
   - A list of mapping rules
   - Each mapping rule takes
     - A map of filters for users