feat: add typed readJSON overload for package.json

.archgate/adrs/ARCH-006-dependency-policy.rules.ts

@@ -12,9 +12,9 @@ export default {
     "no-unapproved-deps": {
       description: "Production dependencies must be on the approved list",
       async check(ctx) {
-        let pkg: { dependencies?: Record<string, string> };
+        let pkg;
         try {
-          pkg = (await ctx.readJSON("package.json")) as typeof pkg;
+          pkg = await ctx.readJSON("package.json");
         } catch {
           return; // No package.json — nothing to check
         }

.archgate/adrs/ARCH-013-version-synchronization.rules.ts

@@ -7,9 +7,7 @@ export default {
         "softwareVersion in docs/astro.config.mjs must match package.json version",
       severity: "error",
       async check(ctx) {
-        const pkgJson = (await ctx.readJSON("package.json")) as {
-          version?: string;
-        };
+        const pkgJson = await ctx.readJSON("package.json");
         if (!pkgJson.version) return;
 
         let astroConfig: string;
@@ -38,10 +36,7 @@ export default {
         "optionalDependencies versions must match package.json version",
       severity: "error",
       async check(ctx) {
-        const pkgJson = (await ctx.readJSON("package.json")) as {
-          version?: string;
-          optionalDependencies?: Record<string, string>;
-        };
+        const pkgJson = await ctx.readJSON("package.json");
         if (!pkgJson.version || !pkgJson.optionalDependencies) return;
 
         for (const [dep, depVersion] of Object.entries(

src/engine/runner.ts

@@ -166,7 +166,7 @@ function createRuleContext(
       return Bun.file(absPath).text();
     },
 
-    readJSON(path: string): Promise<unknown> {
+    readJSON(path: string): Promise<any> {
       const absPath = safePath(projectRoot, path);
       return Bun.file(absPath).json();
     },

src/formats/rules.ts

@@ -35,6 +35,31 @@ export interface RuleReport {
   info(detail: Omit<ViolationDetail, "ruleId" | "adrId" | "severity">): void;
 }
 
+// --- Package JSON ---
+
+export interface PackageJson {
+  name?: string;
+  version?: string;
+  description?: string;
+  main?: string;
+  module?: string;
+  types?: string;
+  bin?: string | Record<string, string>;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  private?: boolean;
+  license?: string;
+  repository?: string | { type: string; url: string };
+  engines?: Record<string, string>;
+  files?: string[];
+  workspaces?: string[] | { packages: string[] };
+  catalog?: Record<string, string>;
+  [key: string]: unknown;
+}
+
 // --- Rule Context ---
 
 export interface RuleContext {
@@ -45,6 +70,7 @@ export interface RuleContext {
   grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;
   grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;
   readFile(path: string): Promise<string>;
+  readJSON(path: "package.json"): Promise<PackageJson>;
   readJSON(path: string): Promise<unknown>;
   report: RuleReport;
 }

src/helpers/rules-shim.ts

@@ -42,6 +42,29 @@ declare interface RuleReport {
   ): void;
 }
 
+declare interface PackageJson {
+  name?: string;
+  version?: string;
+  description?: string;
+  main?: string;
+  module?: string;
+  types?: string;
+  bin?: string | Record<string, string>;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  private?: boolean;
+  license?: string;
+  repository?: string | { type: string; url: string };
+  engines?: Record<string, string>;
+  files?: string[];
+  workspaces?: string[] | { packages: string[] };
+  catalog?: Record<string, string>;
+  [key: string]: unknown;
+}
+
 declare interface RuleContext {
   projectRoot: string;
   scopedFiles: string[];
@@ -50,6 +73,7 @@ declare interface RuleContext {
   grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;
   grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;
   readFile(path: string): Promise<string>;
+  readJSON(path: "package.json"): Promise<PackageJson>;
   readJSON(path: string): Promise<unknown>;
   report: RuleReport;
 }