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

{src_auth_perms_sync-0.5.0 → src_auth_perms_sync-0.7.0}/.github/workflows/validate.yml

@@ -127,6 +127,7 @@ jobs:
     runs-on: ubuntu-24.04
     env:
       MARKDOWNLINT_CLI2_VERSION: "0.22.1"
+      MARKDOWNLINT_RELATIVE_LINKS_VERSION: "5.1.0"
 
     steps:
       - name: Check out code
@@ -139,10 +140,14 @@ jobs:
         uses: actions/cache@v5
         with:
           path: ~/.npm
-          key: npm-${{ runner.os }}-markdownlint-cli2-${{ env.MARKDOWNLINT_CLI2_VERSION }}
+          key: npm-${{ runner.os }}-markdownlint-cli2-${{ env.MARKDOWNLINT_CLI2_VERSION }}-relative-links-${{ env.MARKDOWNLINT_RELATIVE_LINKS_VERSION }}
 
       - name: Lint Markdown
-        run: npx --yes "markdownlint-cli2@${MARKDOWNLINT_CLI2_VERSION}"
+        run: >
+          npx --yes
+          -p "markdownlint-cli2@${MARKDOWNLINT_CLI2_VERSION}"
+          -p "markdownlint-rule-relative-links@${MARKDOWNLINT_RELATIVE_LINKS_VERSION}"
+          markdownlint-cli2
 
   python:
     name: Validate Python

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

@@ -7,13 +7,13 @@ __pycache__
 .pytest_cache
 .ruff_cache
 .venv
+node_modules/
 *.env*
 *.gql
 *.py[cod]
 *.py[oc]
 *.swp
 *.tsv
-*.yaml
 build/
 dist/
 logs*/
@@ -22,7 +22,4 @@ src-auth-perms-sync-runs/
 wheels/
 
 # Allow
-!.env.example
-!.markdownlint-cli2.yaml
-!maps-example.yaml
-!tests/**/*.yaml
+!examples/

src_auth_perms_sync-0.7.0/.markdownlint-cli2.yaml

@@ -0,0 +1,15 @@
+globs:
+  - "**/*.md"
+ignores:
+  - ".venv/**"
+  - "build/**"
+  - "dist/**"
+  - "node_modules/**"
+modulePaths:
+  - "./node_modules"
+customRules:
+  - markdownlint-rule-relative-links
+config:
+  MD013:
+    line_length: 100
+  relative-links: true

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

@@ -12,7 +12,11 @@
 actionlint
 
 ### Markdown files
-npx --yes markdownlint-cli2@0.22.1
+npx --yes -p markdownlint-cli2@0.22.1 -p markdownlint-rule-relative-links@5.1.0 markdownlint-cli2
+
+### Confusable Unicode characters in non-Python files
+# (ruff RUF001-RUF003 covers Python strings/comments/docstrings)
+uv run python tests/confusables.py
 
 ### Python files
 
@@ -37,7 +41,8 @@ own checks.
 
 ```bash
 # Fast, no network (also what the pre-commit hook runs):
-# lint, format, pyright, unit + fixture tests, CLI rejection matrix,
+# lint, format, pyright, confusable-character scan, unit + fixture
+# tests, CLI rejection matrix,
 # randomized permission invariants
 uv run tests/run.py
 
@@ -97,7 +102,7 @@ uv run ruff format --check src/src_auth_perms_sync/ tests/
 uv run pyright
 uv run python -m unittest discover -s tests
 uv run src-auth-perms-sync --help
-npx --yes markdownlint-cli2@0.22.1
+npx --yes -p markdownlint-cli2@0.22.1 -p markdownlint-rule-relative-links@5.1.0 markdownlint-cli2
 uv build --wheel --sdist --out-dir /tmp/src-auth-perms-sync-release-check --no-create-gitignore
 rm -rf /tmp/src-auth-perms-sync-release-check
 ```
@@ -252,6 +257,10 @@ removed names like `ev`, `ex`, `exc`, `cfg`, `conn`, `resp`, `fn`,
 
 Short names that ARE acceptable (don't rewrite these on sight):
 
+- **Established domain abbreviations**: `org` / `orgs` for Sourcegraph
+  organizations, matching the `sync-saml-orgs` command, the `orgs/`
+  package, and the `sync_saml_orgs` config field. Do not expand these
+  back to `organization(s)` in identifiers.
 - **TypedDict / dataclass fields that mirror the wire format**: `id`,
   `url`, `kind` on `ExternalService` etc. These match GraphQL/JSON
   keys and renaming would break the contract.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-auth-perms-sync
-Version: 0.5.0
+Version: 0.7.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
@@ -170,11 +170,30 @@ for provider in get_result.auth_providers:
 for code_host in get_result.code_hosts:
     ...
 
+# Mapping rules can be passed in memory instead of a maps YAML file —
+# same structure and validation as maps.yaml entries:
+rules: list[src.MappingRule] = [
+    {
+        "name": "Map 1",
+        "users": {"usernameRegexes": [".*"]},
+        "repos": {"codeHostConnection": {"kind": "GITHUB"}},
+    },
+]
+result = src.Set(config, mapping_rules=rules)
+# When files are enabled, the rules actually used are written into the
+# run directory for auditability. Snapshots still gate apply=True unless
+# no_files=True and no_backup=True are both set explicitly.
+
 # Other command wrappers:
 # result = src.Restore(config)
 # result = src.SyncSamlOrgs(config)
 ```
 
+The import API does not read environment variables or `.env` files on its
+own — those apply to the CLI only. Pass every value explicitly to
+`src.Config(...)` (read `os.environ` yourself if you want env-driven
+configuration, as the example above does).
+
 Module mode never touches your `logging` handlers or the root logger — your
 application's logging config stays in charge. To see progress messages:
 
@@ -203,7 +222,7 @@ snapshots that make `--apply` reversible.
 - Environment variables (CLI), or src.Config args (Python import)
   - `SRC_ENDPOINT`
   - `SRC_ACCESS_TOKEN` from a user with site-admin perms
-  - See [.env.example](./.env.example)
+  - See [.env.example](./examples/.env.example)
 
 - YAML maps file
   - By default: `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
@@ -217,7 +236,7 @@ snapshots that make `--apply` reversible.
   - Each mapping rule takes
     - A map of filters for users
     - A map of filters for repos
-  - See [maps-example.yaml](./maps-example.yaml)
+  - See [maps.yaml](./examples/maps.yaml)
   - An empty maps.yaml file is created for you on the first `get` run
 
 ## Usage: Permission sync
@@ -237,7 +256,7 @@ snapshots that make `--apply` reversible.
 
     - Edit `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
     - Add mapping rules under the `maps:` top level key
-    - See [maps-example.yaml](./maps-example.yaml)
+    - See [maps.yaml](./examples/maps.yaml)
 
 3. **Set: Dry run**
 
@@ -278,7 +297,7 @@ snapshots that make `--apply` reversible.
 1. **Get user and org metadata**
 
     ```bash
-    src-auth-perms-sync sync-saml-orgs
+    src-auth-perms-sync sync-saml-orgs --full
     ```
 
     - Queries the Sourcegraph instance for auth providers, users, users' SAML groups, and orgs
@@ -287,12 +306,41 @@ snapshots that make `--apply` reversible.
 2. **Apply org sync**
 
     ```bash
-    src-auth-perms-sync sync-saml-orgs --apply
+    src-auth-perms-sync sync-saml-orgs --full --apply
     ```
 
     - Creates the orgs if they don't exist, and sync the members from the SAML groups to the orgs
     - `--sync-saml-orgs` can also be added to a `set` run, to run both at the same time
 
+3. **Scoped org sync for selected users**
+
+    ```bash
+    src-auth-perms-sync sync-saml-orgs --users alice,bob
+    src-auth-perms-sync sync-saml-orgs --created-after 2026-06-01
+    src-auth-perms-sync sync-saml-orgs --users-without-explicit-perms
+    ```
+
+    - Same user filters as `get` and `set`; a mode flag is required — there
+      is no bare `sync-saml-orgs`
+
+### Org sync behavior
+
+- Org names are `synced-<configID>-<group name>` (non-alphanumeric characters
+  become `-`). The `synced-` prefix marks tool ownership: the sync only ever
+  modifies orgs whose name carries it, so manually created orgs are never touched.
+- The org sync mode is always explicit — no surprises:
+  - **Full** (`sync-saml-orgs --full`, or `set --full` / `--repos*`
+    `--sync-saml-orgs`): converges every synced org against all users. A synced
+    org whose SAML group disappeared has all members removed, but the org itself
+    is kept (its settings survive in case the group comes back).
+  - **Scoped** (user filters on `sync-saml-orgs`, or `set --users` /
+    `--users-without-explicit-perms` / `--created-after` with
+    `--sync-saml-orgs`): syncs org membership for exactly the selected users —
+    per-user additions AND removals, computed from each user's own SAML
+    assertion and org list. Other users' memberships never change, and no full
+    user scan or org member listing is needed, so API traffic stays
+    proportional to the selection.
+
 ## Options
 
 Run `src-auth-perms-sync --help` for options

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

@@ -147,11 +147,30 @@ for provider in get_result.auth_providers:
 for code_host in get_result.code_hosts:
     ...
 
+# Mapping rules can be passed in memory instead of a maps YAML file —
+# same structure and validation as maps.yaml entries:
+rules: list[src.MappingRule] = [
+    {
+        "name": "Map 1",
+        "users": {"usernameRegexes": [".*"]},
+        "repos": {"codeHostConnection": {"kind": "GITHUB"}},
+    },
+]
+result = src.Set(config, mapping_rules=rules)
+# When files are enabled, the rules actually used are written into the
+# run directory for auditability. Snapshots still gate apply=True unless
+# no_files=True and no_backup=True are both set explicitly.
+
 # Other command wrappers:
 # result = src.Restore(config)
 # result = src.SyncSamlOrgs(config)
 ```
 
+The import API does not read environment variables or `.env` files on its
+own — those apply to the CLI only. Pass every value explicitly to
+`src.Config(...)` (read `os.environ` yourself if you want env-driven
+configuration, as the example above does).
+
 Module mode never touches your `logging` handlers or the root logger — your
 application's logging config stays in charge. To see progress messages:
 
@@ -180,7 +199,7 @@ snapshots that make `--apply` reversible.
 - Environment variables (CLI), or src.Config args (Python import)
   - `SRC_ENDPOINT`
   - `SRC_ACCESS_TOKEN` from a user with site-admin perms
-  - See [.env.example](./.env.example)
+  - See [.env.example](./examples/.env.example)
 
 - YAML maps file
   - By default: `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
@@ -194,7 +213,7 @@ snapshots that make `--apply` reversible.
   - Each mapping rule takes
     - A map of filters for users
     - A map of filters for repos
-  - See [maps-example.yaml](./maps-example.yaml)
+  - See [maps.yaml](./examples/maps.yaml)
   - An empty maps.yaml file is created for you on the first `get` run
 
 ## Usage: Permission sync
@@ -214,7 +233,7 @@ snapshots that make `--apply` reversible.
 
     - Edit `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
     - Add mapping rules under the `maps:` top level key
-    - See [maps-example.yaml](./maps-example.yaml)
+    - See [maps.yaml](./examples/maps.yaml)
 
 3. **Set: Dry run**
 
@@ -255,7 +274,7 @@ snapshots that make `--apply` reversible.
 1. **Get user and org metadata**
 
     ```bash
-    src-auth-perms-sync sync-saml-orgs
+    src-auth-perms-sync sync-saml-orgs --full
     ```
 
     - Queries the Sourcegraph instance for auth providers, users, users' SAML groups, and orgs
@@ -264,12 +283,41 @@ snapshots that make `--apply` reversible.
 2. **Apply org sync**
 
     ```bash
-    src-auth-perms-sync sync-saml-orgs --apply
+    src-auth-perms-sync sync-saml-orgs --full --apply
     ```
 
     - Creates the orgs if they don't exist, and sync the members from the SAML groups to the orgs
     - `--sync-saml-orgs` can also be added to a `set` run, to run both at the same time
 
+3. **Scoped org sync for selected users**
+
+    ```bash
+    src-auth-perms-sync sync-saml-orgs --users alice,bob
+    src-auth-perms-sync sync-saml-orgs --created-after 2026-06-01
+    src-auth-perms-sync sync-saml-orgs --users-without-explicit-perms
+    ```
+
+    - Same user filters as `get` and `set`; a mode flag is required — there
+      is no bare `sync-saml-orgs`
+
+### Org sync behavior
+
+- Org names are `synced-<configID>-<group name>` (non-alphanumeric characters
+  become `-`). The `synced-` prefix marks tool ownership: the sync only ever
+  modifies orgs whose name carries it, so manually created orgs are never touched.
+- The org sync mode is always explicit — no surprises:
+  - **Full** (`sync-saml-orgs --full`, or `set --full` / `--repos*`
+    `--sync-saml-orgs`): converges every synced org against all users. A synced
+    org whose SAML group disappeared has all members removed, but the org itself
+    is kept (its settings survive in case the group comes back).
+  - **Scoped** (user filters on `sync-saml-orgs`, or `set --users` /
+    `--users-without-explicit-perms` / `--created-after` with
+    `--sync-saml-orgs`): syncs org membership for exactly the selected users —
+    per-user additions AND removals, computed from each user's own SAML
+    assertion and org list. Other users' memberships never change, and no full
+    user scan or org member listing is needed, so API traffic stays
+    proportional to the selection.
+
 ## Options
 
 Run `src-auth-perms-sync --help` for options

{src_auth_perms_sync-0.5.0 → src_auth_perms_sync-0.7.0}/dev/TODO.md

@@ -1,15 +1,5 @@
 # TODO
 
-## Follow-up: in-memory mapping rules for Set (PLAN.md Track A Phase A4)
-
-The rest of [PLAN.md](./PLAN.md) is implemented (src-py-lib v0.3.0 +
-the consumer refactor-logging-and-files PR). The one deliberately
-deferred piece, marked optional in the plan: let module callers pass
-parsed mapping rules to `Set` instead of a maps file, so the full
-get → assemble → dry-run loop never touches disk. Snapshots must stay
-on disk for `--apply` (reversibility invariant); `no_files` + `apply`
-must keep requiring `no_backup`.
-
 ## High priority: Remote trigger on demand
 
 - Sourcegraph webhook for new user coming in v7.4.0
@@ -88,7 +78,7 @@ If/when we revisit:
 
 Phase 1 now avoids per-repo username sets for non-overlapping full-set maps.
 If memory remains too high after re-measuring, implement the Phase 2 grouped
-plan in [mapping-efficiency.md](./mapping-efficiency.md): combine map-entry
+plan in [mapping-efficiency.md](./memory-analysis/mapping-efficiency.md): combine map-entry
 overlays into final groups of repos that share the same desired username tuple.
 
 ## Low priority: Expand group-membership filters beyond SAML

{src_auth_perms_sync-0.5.0 → src_auth_perms_sync-0.7.0}/dev/engineering-requests.md

@@ -1,7 +1,7 @@
 # Engineering requests
 
 Use this when opening Sourcegraph Engineering issues from memory-efficiency
-evidence. Capture steps stay in [memory-efficiency.md](./memory-efficiency.md);
+evidence. Capture steps stay in [memory-efficiency.md](./memory-analysis/memory-efficiency.md);
 this file keeps the request-ready problem statement, evidence, proposed API
 shape, and copy/paste issue text.
 
@@ -85,16 +85,16 @@ small `set` command. Instance: single `pgsql-0` on an 8-core node.
 
 Observed during the concurrent captures:
 
-- `pgsql-0` CPU (`kubectl top`): 7,636–7,683 millicores of 8,000 (saturated).
-- `frontend` / `gitserver` CPU: 124–138m / 2–3m (idle bystanders).
+- `pgsql-0` CPU (`kubectl top`): 7,636-7,683 millicores of 8,000 (saturated).
+- `frontend` / `gitserver` CPU: 124-138m / 2-3m (idle bystanders).
 - `pg_stat_activity`: 29 active statements, all
   `permsStore.ListUserPermissions`, **zero wait events** — pure CPU, no lock
   contention.
 - `pg_stat_statements`: `permsStore.ListUserPermissions` at 24,026 calls,
   27,635.6s total, 1,150ms mean.
-- Per-client capture throughput: 23 users/sec solo → 2–4 users/sec at 4-way
+- Per-client capture throughput: 23 users/sec solo → 2-4 users/sec at 4-way
   concurrency.
-- Aggregate throughput: 8–16 users/sec at 4-way — **below the 23 users/sec a
+- Aggregate throughput: 8-16 users/sec at 4-way — **below the 23 users/sec a
   single client achieves alone** (negative scaling).
 - ALB (CloudWatch): no 5xx, no rejected connections — the edge and frontend
   are not the bottleneck.
@@ -104,7 +104,7 @@ Observed during the concurrent captures:
 Implications for the engineering request:
 
 - A single per-user `permissionsInfo.repositories(source: API)` read costs
-  roughly 0.3–0.4s of Postgres CPU at this state size (1,150ms mean execution
+  roughly 0.3-0.4s of Postgres CPU at this state size (1,150ms mean execution
   under contention), so one operator at modest parallelism can saturate the
   database by itself, and two concurrent operators degrade each other below
   single-operator throughput.
@@ -112,7 +112,7 @@ Implications for the engineering request:
   client read timeout, retries re-run the same expensive queries, adding load
   exactly when the database is saturated.
 - A bulk read API (one query returning explicit grants for many users or for
-  whole repos) would replace ~10,000 × ~1s statements per capture with a
+  whole repos) would replace ~10,000 x ~1s statements per capture with a
   single scan, and would also make concurrent operators viable.
 
 ## Sourcegraph codepath findings
@@ -142,7 +142,7 @@ from `github.com/sourcegraph/sourcegraph`:
 ## Presence-check resolver internals (2026-06-12)
 
 Measured on the 10k-user / 50k-repo test instance, the presence probe
-`User.permissionsInfo.repositories(source: API, first: 1)` costs 225–350ms of
+`User.permissionsInfo.repositories(source: API, first: 1)` costs 225-350ms of
 server work per user, and alias batching barely helps (21,004 single-user
 probes averaged 351.6ms; 25-user batches averaged 5,616ms ≈ 224.7ms/user). A
 single `set --users-without-explicit-perms` run probing all 10,002 users at
@@ -180,7 +180,7 @@ Client-side mitigation shipped in `src-auth-perms-sync` (2026-06-12):
 locally BEFORE probing, so probes scale with the rule-matched user count
 instead of the instance's user count, and user hydration runs as aliased
 25-user batches instead of one `UserByID` request per user. The remaining
-inherent cost — ~225ms × probed user — is exactly what the
+inherent cost — ~225ms x probed user — is exactly what the
 presence/filter API requested below would remove, and
 `get --users-without-explicit-perms` still has to probe every active user
 because its semantics are instance-wide.

{src_auth_perms_sync-0.5.0 → src_auth_perms_sync-0.7.0}/dev/memory-analysis/mapping-efficiency.md

@@ -64,7 +64,7 @@ user-group-b -> repo-group-2
 Each `maps:` entry is naturally a grouped rule:
 
 ```text
-selected users × selected repos
+selected users x selected repos
 ```
 
 The maps schema keeps this restrictive: `users:` and `repos:` are selector
@@ -91,7 +91,7 @@ The old full-set planner immediately expanded every map entry into:
 repo_id -> set(username)
 ```
 
-That is expensive for rectangular maps such as `10000 users × 1000 repos`:
+That is expensive for rectangular maps such as `10000 users x 1000 repos`:
 the username strings are shared, but each repo owns a large Python set with one
 hash-table entry per planned grant.
 

{src_auth_perms_sync-0.5.0 → src_auth_perms_sync-0.7.0}/dev/memory-analysis/memory-efficiency.md

@@ -4,7 +4,7 @@ Use this when full snapshot capture or full-set apply is slow. The goal is to
 correlate `src-auth-perms-sync` structured logs with Sourcegraph Jaeger spans
 and pod/Postgres load. Request-ready evidence and copy/paste text for
 Sourcegraph Engineering live in
-[engineering-requests.md](./engineering-requests.md).
+[engineering-requests.md](../engineering-requests.md).
 
 ## Capture a focused trace
 
@@ -157,7 +157,7 @@ The lower-level helper remains available for focused profiling outside a full
 e2e run:
 
 ```bash
-dev/memory-efficiency-monitor-sourcegraph.sh \
+dev/memory-analysis/memory-efficiency-monitor-sourcegraph.sh \
   --namespace m \
   --output-dir /tmp/src-auth-perms-sync-sourcegraph-load-$(date -u +%Y%m%d-%H%M%S)
 ```
@@ -174,4 +174,4 @@ run.
 
 Request-ready trace findings, stress evidence, Sourcegraph codepath notes,
 proposed GraphQL APIs, and copy/paste issue text now live in
-[engineering-requests.md](./engineering-requests.md).
+[engineering-requests.md](../engineering-requests.md).

src_auth_perms_sync-0.7.0/examples/import.py

@@ -0,0 +1,63 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["src-auth-perms-sync"]
+# ///
+"""Sync Sourcegraph repo permissions from your own Python code.
+
+export SRC_ENDPOINT="https://sourcegraph.example.com"
+export SRC_ACCESS_TOKEN="sgp_..."  # site-admin token
+uv run example-import.py
+"""
+
+import logging
+import os
+
+import src_auth_perms_sync as src
+
+# Configure your logger
+logging.basicConfig(level=logging.INFO)
+
+# The import API does not read environment variables or .env files on its
+# own (the CLI does); pass every value explicitly.
+config = src.Config(
+    src_endpoint=os.environ["SRC_ENDPOINT"],
+    src_access_token=os.environ["SRC_ACCESS_TOKEN"],
+)
+
+# Discover the instance's auth providers and code hosts
+discovery = src.Get(config)
+for auth_provider in discovery.auth_providers:
+    print("auth provider:", auth_provider.get("displayName"))
+for code_host in discovery.code_hosts:
+    print("code host:", code_host.get("displayName"))
+
+# Configure your mapping rules
+mapping_rules: list[src.MappingRule] = [
+    {
+        "name": "LOB1-GROUP1 members get the LOB1-SA1 repos",
+        "users": {"authProvider": {"samlGroup": "LOB1-GROUP1"}},
+        "repos": {"codeHostConnection": {"username": "LOB1-SA1"}},
+    },
+    {
+        "name": "LOB2-GROUP2 members get the LOB2-SA2 repos",
+        "users": {"authProvider": {"samlGroup": "LOB2-GROUP2"}},
+        "repos": {"codeHostConnection": {"username": "LOB2-SA2"}},
+    },
+]
+
+# Run the set dry run, also syncing SAML groups to Sourcegraph organizations
+result = src.Set(
+    config.model_copy(update={"full": True, "apply": False, "sync_saml_orgs": True}),
+    mapping_rules=mapping_rules,
+)
+# Print if it succeeded
+print("permission sync dry run:", "ok" if result else "failed")
+
+# Run the set apply, also syncing SAML groups to Sourcegraph organizations
+result = src.Set(
+    config.model_copy(update={"full": True, "apply": True, "sync_saml_orgs": True}),
+    mapping_rules=mapping_rules,
+)
+
+# Print if it succeeded
+print("permission sync apply:", "ok" if result else "failed")