@oddessentials/repo-standards 4.1.0 → 4.3.0

package/scripts/detect-bazel.ts

@@ -0,0 +1,82 @@
+// scripts/detect-bazel.ts
+
+/**
+ * Standalone Bazel detection utility.
+ * Does NOT require Bazel to be installed.
+ * Only checks repo-root markers to avoid false positives from vendored deps.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export interface BazelDetectionResult {
+  /** Whether Bazel markers were detected at repo root */
+  detected: boolean;
+  /** Bazel mode: bzlmod (MODULE.bazel) or workspace (WORKSPACE*) */
+  mode?: "bzlmod" | "workspace";
+  /** List of detected marker files */
+  markers: string[];
+}
+
+/** Root-level markers that indicate a Bazel repo */
+const ROOT_MARKERS = {
+  bzlmod: ["MODULE.bazel"],
+  workspace: ["WORKSPACE.bazel", "WORKSPACE"],
+};
+
+/** Optional markers that support Bazel but don't trigger detection alone */
+const OPTIONAL_MARKERS = [".bazelrc", ".bazelversion"];
+
+/**
+ * Detect Bazel at repo root only.
+ * Does NOT scan subdirectories for BUILD files (avoids vendored deps false positives).
+ *
+ * @param repoRoot - Absolute path to repository root
+ * @returns Detection result with mode and found markers
+ */
+export function detectBazel(repoRoot: string): BazelDetectionResult {
+  const foundMarkers: string[] = [];
+  let mode: "bzlmod" | "workspace" | undefined;
+
+  // Check bzlmod first (preferred)
+  for (const marker of ROOT_MARKERS.bzlmod) {
+    if (fs.existsSync(path.join(repoRoot, marker))) {
+      foundMarkers.push(marker);
+      mode = "bzlmod";
+    }
+  }
+
+  // Check workspace if no bzlmod
+  if (!mode) {
+    for (const marker of ROOT_MARKERS.workspace) {
+      if (fs.existsSync(path.join(repoRoot, marker))) {
+        foundMarkers.push(marker);
+        mode = "workspace";
+        break; // Only need one workspace marker
+      }
+    }
+  }
+
+  // Check optional markers (don't affect detection, just informational)
+  for (const marker of OPTIONAL_MARKERS) {
+    if (fs.existsSync(path.join(repoRoot, marker))) {
+      foundMarkers.push(marker);
+    }
+  }
+
+  return {
+    detected: mode !== undefined,
+    mode,
+    markers: foundMarkers,
+  };
+}
+
+// CLI entrypoint for manual testing
+if (
+  import.meta.url.startsWith("file:") &&
+  process.argv[1]?.includes("detect-bazel")
+) {
+  const targetDir = process.argv[2] || process.cwd();
+  const result = detectBazel(path.resolve(targetDir));
+  console.log(JSON.stringify(result, null, 2));
+}

package/scripts/generate-instructions.ts

@@ -0,0 +1,174 @@
+// scripts/generate-instructions.ts
+//
+// Generates instructions.md from a stack+CI specific JSON file.
+// Usage: npx ts-node-esm scripts/generate-instructions.ts [config-file]
+// Example: npm run generate:instructions standards.python.github-actions.json
+// Default: config/standards.typescript-js.github-actions.json
+
+import fs from "node:fs";
+import path from "node:path";
+
+interface StackHints {
+  exampleTools?: string[];
+  exampleConfigFiles?: string[];
+  notes?: string;
+  verification?: string;
+  requiredFiles?: string[];
+  optionalFiles?: string[];
+  requiredScripts?: string[];
+}
+
+interface ChecklistItem {
+  id: string;
+  label: string;
+  description: string;
+  ciHints?: Record<string, { job?: string; stage?: string }>;
+  stack?: StackHints;
+}
+
+interface StackChecklistJson {
+  version: number;
+  stack: string;
+  stackLabel: string;
+  ciSystems: string[];
+  checklist: {
+    core: ChecklistItem[];
+    recommended: ChecklistItem[];
+    optionalEnhancements: ChecklistItem[];
+  };
+}
+
+/**
+ * Generate 2-5 high-level bullets from a checklist item.
+ */
+function generateBullets(item: ChecklistItem): string[] {
+  const bullets: string[] = [];
+  const stack = item.stack;
+
+  // Bullet 1: Core purpose from description
+  bullets.push(item.description);
+
+  // Bullet 2: Required files if any
+  if (stack?.requiredFiles?.length) {
+    const files = stack.requiredFiles.join(", ");
+    bullets.push(`Ensure ${files} exists in the repository.`);
+  }
+
+  // Bullet 3: Optional files mention
+  if (stack?.optionalFiles?.length) {
+    const files = stack.optionalFiles.slice(0, 3).join(", ");
+    const more = stack.optionalFiles.length > 3 ? " and others" : "";
+    bullets.push(`Consider adding ${files}${more} if applicable.`);
+  }
+
+  // Bullet 4: Required scripts
+  if (stack?.requiredScripts?.length) {
+    const scripts = stack.requiredScripts.map((s) => `\`${s}\``).join(", ");
+    bullets.push(`Define a ${scripts} script or equivalent command.`);
+  }
+
+  // Bullet 5: Notes-based guidance (if short enough)
+  if (stack?.notes && stack.notes.length < 150) {
+    bullets.push(stack.notes);
+  }
+
+  // Limit to 5 bullets
+  return bullets.slice(0, 5);
+}
+
+function generateSection(title: string, items: ChecklistItem[]): string {
+  if (items.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push(`## ${title}`);
+  lines.push("");
+
+  for (const item of items) {
+    lines.push(`### ${item.label}`);
+    lines.push("");
+
+    const bullets = generateBullets(item);
+    for (const bullet of bullets) {
+      lines.push(`- ${bullet}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function main() {
+  const rootDir = process.cwd();
+
+  // Accept config file as CLI argument, default to TypeScript+GitHub Actions
+  const configArg = process.argv[2];
+  let inputPath: string;
+
+  if (configArg) {
+    // If argument provided, resolve relative to config/ or as absolute
+    if (path.isAbsolute(configArg)) {
+      inputPath = configArg;
+    } else if (
+      configArg.startsWith("config/") ||
+      configArg.startsWith("config\\")
+    ) {
+      inputPath = path.join(rootDir, configArg);
+    } else {
+      inputPath = path.join(rootDir, "config", configArg);
+    }
+  } else {
+    inputPath = path.join(
+      rootDir,
+      "config",
+      "standards.typescript-js.github-actions.json",
+    );
+  }
+
+  // Derive output filename from input (e.g., standards.python.json -> instructions.python.md)
+  const inputBasename = path.basename(inputPath, ".json");
+  const outputBasename = inputBasename.replace(/^standards\./, "instructions.");
+  const outputPath = path.join(rootDir, `${outputBasename}.md`);
+
+  if (!fs.existsSync(inputPath)) {
+    console.error(`Input file not found: ${inputPath}`);
+    console.error("Usage: npm run generate:instructions [config-file]");
+    console.error(
+      "Example: npm run generate:instructions standards.python.github-actions.json",
+    );
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(inputPath, "utf8");
+  const data: StackChecklistJson = JSON.parse(raw);
+
+  const lines: string[] = [];
+
+  // Header
+  lines.push("# Repository Standards Instructions");
+  lines.push("");
+  lines.push(`> Auto-generated from \`${path.relative(rootDir, inputPath)}\``);
+  lines.push(`> Stack: ${data.stackLabel} | CI: ${data.ciSystems.join(", ")}`);
+  lines.push("");
+  lines.push(
+    "This document provides high-level guidance for an autonomous coding agent to bring a repository into compliance with the defined standards.",
+  );
+  lines.push("");
+
+  // Generate sections
+  lines.push(generateSection("Core Requirements", data.checklist.core));
+  lines.push(
+    generateSection("Recommended Practices", data.checklist.recommended),
+  );
+  lines.push(
+    generateSection(
+      "Optional Enhancements",
+      data.checklist.optionalEnhancements,
+    ),
+  );
+
+  // Write output
+  fs.writeFileSync(outputPath, lines.join("\n"));
+  console.log(`Wrote ${outputPath}`);
+}
+
+main();

package/scripts/generate-standards.ts

@@ -0,0 +1,247 @@
+// scripts/generate-standards.ts
+
+import fs from "node:fs";
+import path from "node:path";
+
+type StackId = "typescript-js" | "csharp-dotnet" | "python" | "rust" | "go";
+type CiSystem = "azure-devops" | "github-actions";
+
+interface StackMeta {
+  label: string;
+  languageFamily: string;
+}
+
+interface CiHintsForSystem {
+  stage?: string;
+  job?: string;
+}
+
+type CiHints = Partial<Record<CiSystem, CiHintsForSystem>>;
+
+/**
+ * Bazel execution hints for individual checklist items.
+ * Commands are actual Bazel invocations (e.g., "bazel test //..."),
+ * NOT assumed pattern labels.
+ */
+interface BazelHints {
+  /** Bazel commands to run (e.g., "bazel test //...", "bazel run //tools/lint") */
+  commands?: string[];
+  /** Recommended target conventions (documentation only, not assumed to exist) */
+  recommendedTargets?: string[];
+  /** Usage notes for this check in Bazel context */
+  notes?: string;
+}
+
+interface StackHints {
+  exampleTools?: string[];
+  exampleConfigFiles?: string[];
+  notes?: string;
+  // Human‑readable verification instructions
+  verification?: string;
+  // Machine‑readable additions (all optional)
+  requiredFiles?: string[];
+  optionalFiles?: string[];
+  requiredScripts?: string[];
+  // Either-or file compliance: at least one of these files must exist
+  anyOfFiles?: string[];
+  // Version pinning guidance for deterministic CI
+  pinningNotes?: string;
+  machineCheck?: {
+    command: string;
+    expectExitCode?: number;
+    description?: string;
+  };
+  // Bazel execution hints (v3+)
+  bazelHints?: BazelHints;
+}
+
+interface ChecklistItemMaster {
+  id: string;
+  label: string;
+  description: string;
+  appliesTo: {
+    stacks: StackId[];
+    ciSystems?: CiSystem[];
+  };
+  ciHints?: CiHints;
+  stackHints?: Partial<Record<StackId, StackHints>>;
+}
+
+interface ChecklistSection {
+  core: ChecklistItemMaster[];
+  recommended: ChecklistItemMaster[];
+  optionalEnhancements: ChecklistItemMaster[];
+}
+
+interface MigrationStep {
+  step: number;
+  title: string;
+  description: string;
+  focusIds?: string[];
+  notes?: string;
+}
+
+interface Meta {
+  defaultCoverageThreshold?: number;
+  complexityChecks?: {
+    enabledByDefault?: boolean;
+    description?: string;
+  };
+  qualityGatePolicy?: {
+    preferSoftFailOnLegacy?: boolean;
+    description?: string;
+  };
+  migrationGuide?: MigrationStep[];
+}
+
+interface MasterJson {
+  version: number;
+  meta?: Meta;
+  ciSystems: CiSystem[];
+  stacks: Record<StackId, StackMeta>;
+  checklist: ChecklistSection;
+}
+
+interface StackItem {
+  id: string;
+  label: string;
+  description: string;
+  ciHints?: CiHints;
+  // For the filtered file, this is the single stack’s hints including verification
+  stack?: StackHints;
+}
+
+interface StackChecklistJson {
+  version: number;
+  stack: StackId;
+  stackLabel: string;
+  ciSystems: CiSystem[];
+  meta?: Meta;
+  checklist: {
+    core: StackItem[];
+    recommended: StackItem[];
+    optionalEnhancements: StackItem[];
+  };
+}
+
+function filterSectionForStackAndCi(
+  items: ChecklistItemMaster[],
+  stack: StackId,
+  ciSystem?: CiSystem,
+): StackItem[] {
+  return items
+    .filter((item) => {
+      if (!item.appliesTo.stacks.includes(stack)) return false;
+
+      if (ciSystem && item.appliesTo.ciSystems) {
+        return item.appliesTo.ciSystems.includes(ciSystem);
+      }
+      return true;
+    })
+    .map((item) => {
+      const stackHint = item.stackHints?.[stack];
+
+      const result: StackItem = {
+        id: item.id,
+        label: item.label,
+        description: item.description,
+      };
+
+      if (item.ciHints) {
+        if (ciSystem) {
+          const perSystem = item.ciHints[ciSystem];
+          if (perSystem) {
+            result.ciHints = { [ciSystem]: perSystem };
+          }
+        } else {
+          result.ciHints = item.ciHints;
+        }
+      }
+
+      if (stackHint) {
+        // Includes exampleTools, exampleConfigFiles, notes, verification
+        result.stack = stackHint;
+      }
+
+      return result;
+    });
+}
+
+function generateStackJson(
+  master: MasterJson,
+  stack: StackId,
+  ciSystem?: CiSystem,
+): StackChecklistJson {
+  const stackMeta = master.stacks[stack];
+  const ciSystems = ciSystem ? [ciSystem] : master.ciSystems;
+
+  return {
+    version: master.version,
+    stack,
+    stackLabel: stackMeta?.label ?? stack,
+    ciSystems,
+    meta: master.meta,
+    checklist: {
+      core: filterSectionForStackAndCi(master.checklist.core, stack, ciSystem),
+      recommended: filterSectionForStackAndCi(
+        master.checklist.recommended,
+        stack,
+        ciSystem,
+      ),
+      optionalEnhancements: filterSectionForStackAndCi(
+        master.checklist.optionalEnhancements,
+        stack,
+        ciSystem,
+      ),
+    },
+  };
+}
+
+// --- entrypoint ---
+const rootDir = path.join(process.cwd());
+const masterPath = path.join(rootDir, "config", "standards.json");
+
+const raw = fs.readFileSync(masterPath, "utf8");
+const master: MasterJson = JSON.parse(raw);
+
+// args: stack [ciSystem]
+// args: stack [ciSystem]
+const STACK_ALIASES: Record<string, StackId> = {
+  dotnet: "csharp-dotnet",
+  csharp: "csharp-dotnet",
+  ts: "typescript-js",
+  js: "typescript-js",
+  python: "python",
+  py: "python",
+  "typescript-js": "typescript-js",
+  "csharp-dotnet": "csharp-dotnet",
+  rust: "rust",
+  rs: "rust",
+  go: "go",
+  golang: "go",
+};
+
+const rawArg = process.argv[2] || "typescript-js";
+const targetStack = STACK_ALIASES[rawArg.toLowerCase()];
+
+if (!targetStack) {
+  console.error(`Unknown stack: ${rawArg}`);
+  console.error(
+    `Available stacks: ${["typescript-js", "csharp-dotnet", "python", "rust", "go"].join(", ")}`,
+  );
+  process.exit(1);
+}
+
+const targetCiSystem = process.argv[3] as CiSystem | undefined;
+
+const stackJson = generateStackJson(master, targetStack, targetCiSystem);
+
+const outDir = path.join(rootDir, "config");
+fs.mkdirSync(outDir, { recursive: true });
+
+const ciSuffix = targetCiSystem ? `.${targetCiSystem}` : "";
+const outPath = path.join(outDir, `standards.${targetStack}${ciSuffix}.json`);
+
+fs.writeFileSync(outPath, JSON.stringify(stackJson, null, 2) + "\n");
+
+console.log(`Wrote ${outPath}`);

package/scripts/sync-manifest-version.cjs

@@ -0,0 +1,32 @@
+/**
+ * Syncs manifest.json version with package.json
+ * Called by semantic-release exec plugin during release
+ *
+ * @see https://github.com/semantic-release/exec
+ */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const pkgPath = path.join(process.cwd(), "package.json");
+const manifestPath = path.join(process.cwd(), "manifest.json");
+
+if (!fs.existsSync(manifestPath)) {
+  console.log("[sync-manifest] No manifest.json found, skipping");
+  process.exit(0);
+}
+
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+
+manifest.version = pkg.version;
+fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+// Run prettier to ensure consistent formatting
+try {
+  execSync("npx prettier --write manifest.json", { stdio: "inherit" });
+} catch {
+  console.log("[sync-manifest] prettier not available, skipping format");
+}
+
+console.log(`[sync-manifest] Updated manifest.json to ${pkg.version}`);