More strict config rules

Author: UltraProdigy

README.md

@@ -23,7 +23,7 @@ The normal flow is:
 
 1. You run `Org-Label-Sync` manually.
 2. It first calls `Config-Label_Sync`.
-3. `Config-Label_Sync` reads the labels on this repository and rewrites `config/labels.jsonc` so the file matches the repo's current managed labels.
+3. `Config-Label_Sync` reads the labels on this repository and rewrites `config/labels.jsonc` so the file matches the repo's current labels.
 4. If that file changed, `Config-Label_Sync` commits and pushes the update.
 5. That config change triggers `Validate-Configs`.
 6. `Org-Label-Sync` then checks out the latest default branch, validates the config again, and syncs labels across the organization.
@@ -86,7 +86,7 @@ Example:
 
 This is the managed label set that gets created or updated across the org.
 
-It is normally maintained automatically by `Config-Label_Sync`, based on the labels currently present on this repository after excluding auto-pruned labels.
+It is normally maintained automatically by `Config-Label_Sync`, based on the labels currently present on this repository.
 
 Each label object uses:
 
@@ -108,21 +108,34 @@ Example:
 
 ### `config/auto-pruned-labels.jsonc`
 
-This is the list of labels that should always be removed from synced repositories.
+This is the list of exact labels that should be removed from synced repositories when they are not managed by `config/labels.jsonc`.
 
-The starter file is prefilled with GitHub's default labels:
+Each entry must include:
 
-- `bug`
-- `documentation`
-- `duplicate`
-- `enhancement`
-- `good first issue`
-- `help wanted`
-- `invalid`
-- `question`
-- `wontfix`
+- `name`
+- `color`
+- `description`
+
+The starter file is prefilled with GitHub's default labels as exact specs:
+
+```jsonc
+[
+  {
+    "name": "bug",
+    "color": "d73a4a",
+    "description": "Something isn't working"
+  },
+  {
+    "name": "enhancement",
+    "color": "a2eeef",
+    "description": "New feature or request"
+  }
+]
+```
+
+`Org-Label-Sync` only deletes a configured auto-pruned label when the target repository label has the same name casing, color, and description. A custom label such as `Enhancement`, or an `enhancement` label with a different description or color, is not deleted by this file.
 
-If any of those labels exist on this repo, `Config-Label_Sync` excludes them from `labels.jsonc`. If they exist on target repos, `Org-Label-Sync` deletes them.
+Managed labels are the source of truth. If a label exists in `config/labels.jsonc`, it is created or updated on target repositories and is not deleted by `config/auto-pruned-labels.jsonc`, even when it has the same name as an auto-pruned default.
 
 ### `config/repository-filter.jsonc`
 
@@ -173,8 +186,8 @@ What it does:
 1. Checks out the default branch
 2. Loads shared settings from `config/properties.jsonc`
 3. Reads the current labels on the source repository
-4. Removes any labels listed in `config/auto-pruned-labels.jsonc`
-5. Rewrites `config/labels.jsonc` so it exactly matches the remaining labels
+4. Rewrites `config/labels.jsonc` so it exactly matches the source repository labels
+5. Validates `config/auto-pruned-labels.jsonc` so exact default-delete specs remain well-formed
 6. Commits and pushes the change if the config was updated
 
 This workflow is the bridge between "the labels on this repo right now" and "the managed config we sync elsewhere."
@@ -202,7 +215,7 @@ Validation includes:
 - duplicate whitelist and blacklist detection
 - invalid colors
 - invalid repo names
-- overlap detection between `labels.jsonc` and `auto-pruned-labels.jsonc`
+- exact auto-pruned label shape validation
 - validation for the shared config used by `Remove-Labels`
 
 ### `Org-Label-Sync`
@@ -228,7 +241,7 @@ What it does:
 5. Discovers repos in the configured organization
 6. Applies `config/repository-filter.jsonc`
 7. Creates or updates labels from `config/labels.jsonc`
-8. Deletes labels listed in `config/auto-pruned-labels.jsonc`
+8. Deletes labels that exactly match entries in `config/auto-pruned-labels.jsonc` unless that label name is managed by `config/labels.jsonc`
 9. Optionally deletes any other unmanaged labels if `delete_missing` or `deleteMissingByDefault` is enabled
 10. If the run is not a dry run and at least one target repo changed, writes a changelog under `changelogs/YYYY-MM-DD/` and commits it with `[skip ci]`
 
@@ -300,7 +313,7 @@ That token needs enough access to:
 1. Fork or clone this repository into the organization you want to manage.
 2. Create the sync token secret in the repo.
 3. Update `config/properties.jsonc` for your org and repo.
-4. Adjust `config/auto-pruned-labels.jsonc` if you want a different always-delete list.
+4. Adjust `config/auto-pruned-labels.jsonc` if you want different exact default-delete specs.
 5. Configure `config/repository-filter.jsonc` for blacklist mode or whitelist mode.
 6. Set the labels on this repository to the label set you want to manage.
 7. Run `Config-Label_Sync` once if you want to populate `config/labels.jsonc` immediately.
@@ -310,5 +323,5 @@ That token needs enough access to:
 
 - `labels.jsonc` starts empty until you define or sync labels on this repo
 - all repos in the org are targeted unless excluded by `repository-filter.jsonc`
-- GitHub default labels are auto-pruned by default
+- GitHub default labels are auto-pruned by default only when they exactly match the stored name, color, and description and are not managed in `labels.jsonc`
 - deleting unmanaged labels is off by default unless you enable it

config/auto-pruned-labels.jsonc

@@ -1,17 +1,55 @@
 // Example:
 // [
-//   "bug",
-//   "documentation",
-//   "duplicate"
+//   {
+//     "name": "bug",
+//     "color": "d73a4a",
+//     "description": "Something isn't working"
+//   }
 // ]
 [
-  "bug",
-  "documentation",
-  "duplicate",
-  "enhancement",
-  "good first issue",
-  "help wanted",
-  "invalid",
-  "question",
-  "wontfix"
+  {
+    "name": "bug",
+    "color": "d73a4a",
+    "description": "Something isn't working"
+  },
+  {
+    "name": "documentation",
+    "color": "0075ca",
+    "description": "Improvements or additions to documentation"
+  },
+  {
+    "name": "duplicate",
+    "color": "cfd3d7",
+    "description": "This issue or pull request already exists"
+  },
+  {
+    "name": "enhancement",
+    "color": "a2eeef",
+    "description": "New feature or request"
+  },
+  {
+    "name": "good first issue",
+    "color": "7057ff",
+    "description": "Good for newcomers"
+  },
+  {
+    "name": "help wanted",
+    "color": "008672",
+    "description": "Extra attention is needed"
+  },
+  {
+    "name": "invalid",
+    "color": "e4e669",
+    "description": "This doesn't seem right"
+  },
+  {
+    "name": "question",
+    "color": "d876e3",
+    "description": "Further information is requested"
+  },
+  {
+    "name": "wontfix",
+    "color": "ffffff",
+    "description": "This will not be worked on"
+  }
 ]

scripts/lib/config-utils.mjs

@@ -14,6 +14,14 @@ export function normalizeDescription(description) {
   return description ?? "";
 }
 
+export function normalizeLabelSpec(label) {
+  return {
+    name: label.name.trim(),
+    color: normalizeColor(label.color),
+    description: normalizeDescription(label.description),
+  };
+}
+
 export function normalizeName(name) {
   return name.trim().toLowerCase();
 }
@@ -22,6 +30,22 @@ export function normalizeRepositoryRef(value) {
   return value.trim().toLowerCase();
 }
 
+export function labelsExactlyMatch(left, right) {
+  const normalizedLeft = normalizeLabelSpec(left);
+  const normalizedRight = normalizeLabelSpec(right);
+
+  return (
+    normalizedLeft.name === normalizedRight.name
+    && normalizedLeft.color === normalizedRight.color
+    && normalizedLeft.description === normalizedRight.description
+  );
+}
+
+export function labelSpecKey(label) {
+  const normalized = normalizeLabelSpec(label);
+  return `${normalized.name}\0${normalized.color}\0${normalized.description}`;
+}
+
 function stripJsonComments(contents) {
   let result = "";
   let inString = false;

scripts/lib/config-validation.mjs

@@ -1,7 +1,8 @@
 import {
   assert,
+  labelSpecKey,
   normalizeColor,
-  normalizeDescription,
+  normalizeLabelSpec,
   normalizeName,
   normalizeRepositoryRef,
 } from "./config-utils.mjs";
@@ -83,11 +84,7 @@ export function validateLabels(labels) {
       assert(typeof label.description === "string", `Label "${label.name}" has a non-string description.`);
     }
 
-    return {
-      name: label.name.trim(),
-      color: normalizeColor(label.color),
-      description: normalizeDescription(label.description),
-    };
+    return normalizeLabelSpec(label);
   });
 }
 
@@ -97,26 +94,19 @@ export function validateDeleteLabels(deleteLabels) {
   const seen = new Set();
 
   return deleteLabels.map((entry, index) => {
-    assert(typeof entry === "string" && entry.trim(), `Delete label at index ${index} must be a non-empty string.`);
-
-    const name = entry.trim();
-    const key = normalizeName(name);
-    assert(!seen.has(key), `Duplicate delete label detected: "${name}".`);
+    assert(entry && typeof entry === "object" && !Array.isArray(entry), `Delete label at index ${index} must be an object.`);
+    assert(typeof entry.name === "string" && entry.name.trim(), `Delete label at index ${index} is missing a valid name.`);
+    assert(typeof entry.color === "string" && /^[0-9a-fA-F]{6}$/.test(normalizeColor(entry.color)), `Delete label "${entry.name}" must have a 6-character hex color.`);
+    assert(typeof entry.description === "string", `Delete label "${entry.name}" must include a string description.`);
+
+    const normalized = normalizeLabelSpec(entry);
+    const key = labelSpecKey(normalized);
+    assert(!seen.has(key), `Duplicate exact delete label detected: "${normalized.name}".`);
     seen.add(key);
-    return name;
+    return normalized;
   });
 }
 
-export function assertNoLabelOverlap(desiredLabels, deleteLabels) {
-  const desiredKeys = new Set(desiredLabels.map((label) => normalizeName(label.name)));
-  const overlaps = deleteLabels.filter((label) => desiredKeys.has(normalizeName(label)));
-
-  assert(
-    overlaps.length === 0,
-    `Labels cannot exist in both config/labels.jsonc and config/auto-pruned-labels.jsonc: ${overlaps.join(", ")}.`,
-  );
-}
-
 function validateRepositoryEntries(entries, configKey) {
   assert(Array.isArray(entries), `config/repository-filter.jsonc field "${configKey}" must contain an array.`);
 

scripts/sync-config-labels.mjs

@@ -3,7 +3,6 @@ import {
   assert,
   normalizeColor,
   normalizeDescription,
-  normalizeName,
   readJsonc,
   writeJsoncPreservingHeader,
 } from "./lib/config-utils.mjs";
@@ -49,9 +48,8 @@ async function getAllLabels(token, repo) {
   }
 }
 
-function toManagedLabels(labels, deleteLabels) {
+function toManagedLabels(labels) {
   return labels
-    .filter((label) => !deleteLabels.has(normalizeName(label.name)))
     .map((label) => ({
       name: label.name.trim(),
       color: normalizeColor(label.color),
@@ -71,16 +69,14 @@ async function main() {
   const repository = process.env.SOURCE_REPOSITORY ?? properties.sourceRepository;
   assert(repository, "SOURCE_REPOSITORY or GITHUB_REPOSITORY is required.");
 
-  const deleteLabels = new Set(
-    validateDeleteLabels(await readJsonc(autoPrunedLabelsPath)).map((entry) => normalizeName(entry)),
-  );
+  const deleteLabels = validateDeleteLabels(await readJsonc(autoPrunedLabelsPath));
   const repositoryLabels = await getAllLabels(token, repository);
-  const managedLabels = toManagedLabels(repositoryLabels, deleteLabels);
+  const managedLabels = toManagedLabels(repositoryLabels);
 
   await writeJsoncPreservingHeader(labelsPath, managedLabels);
 
   console.log(
-    `Synced ${managedLabels.length} managed labels from ${repository} into config/labels.jsonc after excluding ${deleteLabels.size} auto-pruned labels.`,
+    `Synced ${managedLabels.length} managed labels from ${repository} into config/labels.jsonc. Source labels take precedence over ${deleteLabels.length} exact auto-pruned label specs.`,
   );
 }
 

scripts/sync-labels.mjs

@@ -1,14 +1,14 @@
 import path from "node:path";
 import {
   assert,
+  labelsExactlyMatch,
   normalizeColor,
   normalizeDescription,
   normalizeName,
   normalizeRepositoryRef,
   readJsonc,
 } from "./lib/config-utils.mjs";
 import {
-  assertNoLabelOverlap,
   validateDeleteLabels,
   validateLabels,
   validateProperties,
@@ -171,12 +171,15 @@ function summarizeLabelDiff(existing, desired) {
   return "update";
 }
 
+function isExactAutoPrunedLabel(label, deleteLabels) {
+  return deleteLabels.some((deleteLabel) => labelsExactlyMatch(label, deleteLabel));
+}
+
 async function syncRepository(token, repository, desiredLabels, deleteLabels, deleteMissing) {
   console.log(`\nSyncing ${repository.full_name}`);
   const existingLabels = await getAllLabels(token, repository.full_name);
   const existingByName = new Map(existingLabels.map((label) => [normalizeName(label.name), label]));
   const desiredKeys = new Set(desiredLabels.map((label) => normalizeName(label.name)));
-  const deleteKeys = new Set(deleteLabels.map((label) => normalizeName(label)));
   const result = {
     repository: repository.full_name,
     createdLabels: [],
@@ -238,7 +241,9 @@ async function syncRepository(token, repository, desiredLabels, deleteLabels, de
   }
 
   for (const existing of existingLabels) {
-    if (!deleteKeys.has(normalizeName(existing.name))) {
+    const existingKey = normalizeName(existing.name);
+
+    if (desiredKeys.has(existingKey) || !isExactAutoPrunedLabel(existing, deleteLabels)) {
       continue;
     }
 
@@ -264,7 +269,7 @@ async function syncRepository(token, repository, desiredLabels, deleteLabels, de
     for (const existing of existingLabels) {
       const existingKey = normalizeName(existing.name);
 
-      if (desiredKeys.has(existingKey) || deleteKeys.has(existingKey)) {
+      if (desiredKeys.has(existingKey) || isExactAutoPrunedLabel(existing, deleteLabels)) {
         continue;
       }
 
@@ -303,7 +308,6 @@ async function main() {
   });
   const labels = validateLabels(await readJsonc(labelsPath));
   const deleteLabels = validateDeleteLabels(await readJsonc(autoPrunedLabelsPath));
-  assertNoLabelOverlap(labels, deleteLabels);
   const repositoryFilter = validateRepositoryFilter(await readJsonc(repositoryFilterPath));
   const activeFilterCount = repositoryFilter.useWhitelist ? repositoryFilter.whitelist.size : repositoryFilter.blacklist.size;
   const activeFilterMode = repositoryFilter.useWhitelist ? "whitelist" : "blacklist";