src-auth-perms-sync 0.6.0__tar.gz → 0.8.0__tar.gz

{src_auth_perms_sync-0.6.0 → src_auth_perms_sync-0.8.0}/.github/workflows/release.yml

@@ -83,7 +83,7 @@ jobs:
 
     steps:
       - name: Check out release ref
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -95,7 +95,7 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Cache uv
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: ~/.cache/uv
           key: uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-${{ hashFiles('uv.lock') }}

{src_auth_perms_sync-0.6.0 → src_auth_perms_sync-0.8.0}/.github/workflows/validate.yml

@@ -98,7 +98,7 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
           ref: ${{ inputs.ref || github.ref }}
@@ -127,22 +127,27 @@ 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
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
           ref: ${{ inputs.ref || github.ref }}
 
       - name: Cache npm
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         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
@@ -155,7 +160,7 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -167,7 +172,7 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Cache uv
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: ~/.cache/uv
           key: uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-${{ hashFiles('uv.lock') }}
@@ -180,6 +185,9 @@ jobs:
       - name: Validate lockfile
         run: uv lock --check
 
+      - name: Scan for Unicode characters
+        run: uv run --frozen python tests/unicode_scan.py
+
       - name: Lint Python
         run: uv run --frozen ruff check .
 
@@ -207,7 +215,7 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -219,7 +227,7 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Cache uv
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: ~/.cache/uv
           key: uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-${{ hashFiles('uv.lock') }}

{src_auth_perms_sync-0.6.0 → src_auth_perms_sync-0.8.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.8.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.6.0 → src_auth_perms_sync-0.8.0}/AGENTS.md

@@ -12,7 +12,10 @@
 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
+
+### Non-ASCII characters in tracked text files
+uv run python tests/unicode_scan.py
 
 ### Python files
 
@@ -37,7 +40,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, non-ASCII character scan, unit + fixture
+# tests, CLI rejection matrix,
 # randomized permission invariants
 uv run tests/run.py
 
@@ -59,7 +63,7 @@ uv run tests/run.py --performance --baseline-command "uvx src-auth-perms-sync@la
 uv run tests/run.py --update-golden
 ```
 
-- Fixture cases live in `tests/e2e/fixtures/<case>/` — see the README there
+- 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
@@ -97,7 +101,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
 ```
@@ -160,7 +164,7 @@ gh run watch "${RUN_ID}" --repo "${GH_REPO}" --exit-status
 gh release view "v${VERSION}" --repo "${GH_REPO}"
 ```
 
-## Hard invariants — do not break
+## Hard invariants - do not break
 
 Violating these can silently grant the wrong users access to the wrong
 repos.
@@ -201,31 +205,31 @@ 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. Module
+- `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
+- `shared/` - cross-workflow helpers: Sourcegraph auth-provider/user list
   helpers, shared GraphQL operations and TypedDicts, site-config validation,
   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
+  (`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:
 
-- `permissions/` — repo permission sync (`command.py`, `maps.py`,
+- `permissions/` - repo permission sync (`command.py`, `maps.py`,
   `mapping.py`, `sourcegraph.py`, `snapshot.py`, `apply.py`, `queries.py`,
   `types.py`). Add new mapping filters in `permissions/types.py` and
   `permissions/mapping.py`.
-- `orgs/` — SAML group → Sourcegraph organization sync (`command.py`,
+- `orgs/` - SAML group -> Sourcegraph organization sync (`command.py`,
   `queries.py`, `types.py`).
 
 ## Toolchain
 
 - Python 3.11 + [uv](https://docs.astral.sh/uv/). Never invoke `python`
   directly; always `uv run ...`.
-- `uv run pyright` must be clean. No `# type: ignore` to silence —
+- `uv run pyright` must be clean. No `# type: ignore` to silence -
   fix the underlying type.
 - Local tests use stdlib `unittest`: `uv run python -m unittest discover -s tests`.
 - For Sourcegraph mutation-path changes, also verify by dry-running `--get` /
@@ -252,6 +256,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.
@@ -259,7 +267,7 @@ Short names that ARE acceptable (don't rewrite these on sight):
   `key`, `value`, `name`, `kind`.
 - **Stdlib idioms**: `ctx` for `contextvars.copy_context()`.
 - **Loop / comprehension variables when the type is obvious from one
-  line of context** is still discouraged — prefer `user`, `repo`,
+  line of context** is still discouraged - prefer `user`, `repo`,
   `provider`, `service`, `permission`, `node`, `entry`, `match`,
   `account`, `future`, `executor`, `exception`, `event`, `connection`,
   `response`, `timestamp`, `current`, `outcome`, `index`, `field_name`.

{src_auth_perms_sync-0.6.0 → src_auth_perms_sync-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-auth-perms-sync
-Version: 0.6.0
+Version: 0.8.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
@@ -16,13 +16,13 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: json5>=0.14.0
+Requires-Dist: json5>=0.15.0
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: src-py-lib[otel]==0.3.0
+Requires-Dist: src-py-lib[otel]==0.3.1
 Description-Content-Type: text/markdown
 
 # src-auth-perms-sync
-<!-- HUMAN-MAINTAINED SECTION START — DO NOT EDIT THIS SECTION -->
+<!-- HUMAN-MAINTAINED SECTION START - DO NOT EDIT THIS SECTION -->
 
 src-auth-perms-sync automates Sourcegraph's Explicit Permissions GraphQL API,
 setting user-to-repo permissions based on mapping rules, for example:
@@ -167,10 +167,10 @@ result = src.Set(config)  # truthy on success; result.paths has run artifacts
 get_result = src.Get(config)
 for provider in get_result.auth_providers:
     ...
-for code_host in get_result.code_hosts:
+for code_host_connection in get_result.code_host_connections:
     ...
 
-# Mapping rules can be passed in memory instead of a maps YAML file —
+# 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] = [
     {
@@ -189,7 +189,12 @@ result = src.Set(config, mapping_rules=rules)
 # result = src.SyncSamlOrgs(config)
 ```
 
-Module mode never touches your `logging` handlers or the root logger — your
+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:
 
 ```python
@@ -217,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`
@@ -231,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
@@ -243,7 +248,7 @@ snapshots that make `--apply` reversible.
     ```
 
     - Queries the Sourcegraph instance for auth providers and code host connections
-    - Writes generated reference files `auth-providers.yaml` and `code-hosts.yaml` under
+    - Writes generated reference files `auth-providers.yaml` and `code-host-connections.yaml` under
       `src-auth-perms-sync-runs/<src_endpoint>/`
     - Creates an empty `maps.yaml` if it doesn't exist
 
@@ -251,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**
 
@@ -292,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
@@ -301,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 --users-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` / `--users-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
@@ -315,22 +349,22 @@ Run `src-auth-perms-sync --help` for options
 
 ```text
 src-auth-perms-sync-runs/<src_endpoint>/
-├── auth-providers.yaml
-├── code-hosts.yaml
-├── maps.yaml
-└── runs
-    └── timestamp-command
-        ├── before.json
-        ├── after.json
-        ├── diff.json
-        ├── log.json
-        └── maps.yaml
+|-- auth-providers.yaml
+|-- code-host-connections.yaml
+|-- maps.yaml
+`-- runs
+    `-- timestamp-command
+        |-- before.json
+        |-- after.json
+        |-- diff.json
+        |-- log.json
+        `-- maps.yaml
 ```
 
 - The `src-auth-perms-sync-runs` dir is created under your current working directory
 - The `<src_endpoint>` dir is created with the hostname from `SRC_ENDPOINT`
 - If `maps.yaml` doesn't exist already, it'll be created for you
-- `auth-providers.yaml` and `code-hosts.yaml` are created / replaced by the `get` command,
+- `auth-providers.yaml` and `code-host-connections.yaml` are created / replaced by the `get` command,
   for you to copy values from, to use in your `maps.yaml`
 - Only one `maps.yaml` file can be used at a time per Sourcegraph instance, as each `set --apply`
   command resets the state on the Sourcegraph instance to the `maps.yaml` file which was used
@@ -342,4 +376,4 @@ src-auth-perms-sync-runs/<src_endpoint>/
   - An `after.json` file, capturing the new state
   - A `diff.json` file, a shorter, reviewable file containing the diffs between before and after
 
-<!-- HUMAN-MAINTAINED SECTION END — DO NOT EDIT ABOVE -->
+<!-- HUMAN-MAINTAINED SECTION END - DO NOT EDIT ABOVE -->

{src_auth_perms_sync-0.6.0 → src_auth_perms_sync-0.8.0}/README.md

@@ -1,5 +1,5 @@
 # src-auth-perms-sync
-<!-- HUMAN-MAINTAINED SECTION START — DO NOT EDIT THIS SECTION -->
+<!-- HUMAN-MAINTAINED SECTION START - DO NOT EDIT THIS SECTION -->
 
 src-auth-perms-sync automates Sourcegraph's Explicit Permissions GraphQL API,
 setting user-to-repo permissions based on mapping rules, for example:
@@ -144,10 +144,10 @@ result = src.Set(config)  # truthy on success; result.paths has run artifacts
 get_result = src.Get(config)
 for provider in get_result.auth_providers:
     ...
-for code_host in get_result.code_hosts:
+for code_host_connection in get_result.code_host_connections:
     ...
 
-# Mapping rules can be passed in memory instead of a maps YAML file —
+# 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] = [
     {
@@ -166,7 +166,12 @@ result = src.Set(config, mapping_rules=rules)
 # result = src.SyncSamlOrgs(config)
 ```
 
-Module mode never touches your `logging` handlers or the root logger — your
+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:
 
 ```python
@@ -194,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`
@@ -208,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
@@ -220,7 +225,7 @@ snapshots that make `--apply` reversible.
     ```
 
     - Queries the Sourcegraph instance for auth providers and code host connections
-    - Writes generated reference files `auth-providers.yaml` and `code-hosts.yaml` under
+    - Writes generated reference files `auth-providers.yaml` and `code-host-connections.yaml` under
       `src-auth-perms-sync-runs/<src_endpoint>/`
     - Creates an empty `maps.yaml` if it doesn't exist
 
@@ -228,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**
 
@@ -269,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
@@ -278,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 --users-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` / `--users-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
@@ -292,22 +326,22 @@ Run `src-auth-perms-sync --help` for options
 
 ```text
 src-auth-perms-sync-runs/<src_endpoint>/
-├── auth-providers.yaml
-├── code-hosts.yaml
-├── maps.yaml
-└── runs
-    └── timestamp-command
-        ├── before.json
-        ├── after.json
-        ├── diff.json
-        ├── log.json
-        └── maps.yaml
+|-- auth-providers.yaml
+|-- code-host-connections.yaml
+|-- maps.yaml
+`-- runs
+    `-- timestamp-command
+        |-- before.json
+        |-- after.json
+        |-- diff.json
+        |-- log.json
+        `-- maps.yaml
 ```
 
 - The `src-auth-perms-sync-runs` dir is created under your current working directory
 - The `<src_endpoint>` dir is created with the hostname from `SRC_ENDPOINT`
 - If `maps.yaml` doesn't exist already, it'll be created for you
-- `auth-providers.yaml` and `code-hosts.yaml` are created / replaced by the `get` command,
+- `auth-providers.yaml` and `code-host-connections.yaml` are created / replaced by the `get` command,
   for you to copy values from, to use in your `maps.yaml`
 - Only one `maps.yaml` file can be used at a time per Sourcegraph instance, as each `set --apply`
   command resets the state on the Sourcegraph instance to the `maps.yaml` file which was used
@@ -319,4 +353,4 @@ src-auth-perms-sync-runs/<src_endpoint>/
   - An `after.json` file, capturing the new state
   - A `diff.json` file, a shorter, reviewable file containing the diffs between before and after
 
-<!-- HUMAN-MAINTAINED SECTION END — DO NOT EDIT ABOVE -->
+<!-- HUMAN-MAINTAINED SECTION END - DO NOT EDIT ABOVE -->

{src_auth_perms_sync-0.6.0 → src_auth_perms_sync-0.8.0}/dev/TODO.md

@@ -32,7 +32,7 @@
 - `get --repos <name>` still scans every user's explicit grants to find one
   repo's holders (~400 s at 10k users). A repo-centric read
   (`repository.permissionsInfo.users` + site-admin disambiguation, as the
-  test harness already does) would make it seconds — see the repo-centric
+  test harness already does) would make it seconds - see the repo-centric
   section below.
 
 ## Low priority: Repo-centric path, when users > repos, or for cross-checking
@@ -50,10 +50,10 @@ Reasons we might want to bring it back later:
 - **Targeted snapshots.** A "planned-scope" capture (only the repos
   the mapping rules touch) is faster than a full instance scan when
   the user-centric path is the long pole AND the planned set is small.
-  Would need either a server-side `source` filter on the repo→users
+  Would need either a server-side `source` filter on the repo->users
   connection, or a follow-up user-centric `source: API` query per
   ambiguous (site-admin) user to disambiguate.
-- **Adaptive capture path after SG adds `source` to repo→users.** Once
+- **Adaptive capture path after SG adds `source` to repo->users.** Once
   `RepositoryPermissionsInfo.users(source: PermissionSource)` exists,
   compute the expected request count both ways before snapshotting:
   sum `userCount` across all auth providers and sum `repoCount` across
@@ -70,7 +70,7 @@ If/when we revisit:
    ambiguous-user follow-up to be correct).
 2. Restore `QUERY_REPO_EXPLICIT_USERS` from git history; implement
    `list_repo_explicit_users` returning `(definitely, ambiguous)` and
-   actually consume both buckets — the previous code did neither.
+   actually consume both buckets - the previous code did neither.
 3. Add a CLI flag (e.g. `--cross-check-capture`) gated behind a clear
    "this doubles capture cost" warning.
 
@@ -78,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
@@ -89,7 +89,7 @@ SAML actually persists the group list. Recovery options for each:
 - OIDC has no `allowGroups` field on `OpenIDConnectAuthProvider`.
   `UserClaims` stores only name/email fields; the `groups` claim is never
   parsed. Recovery needs an upstream change to persist the claim.
-- GitHub OAuth has `allowOrgs`, `allowOrgsMap` (org→teams), and
+- GitHub OAuth has `allowOrgs`, `allowOrgsMap` (org->teams), and
   `requiredSsoOrgs`. Org/team checks happen live in `verifyUserOrgs` /
   `verifyUserTeams` and are discarded. Recovery needs an upstream change to
   persist the claim.