@toolbaux/guardian 0.1.0

package/dist/schema/feature-spec.js

@@ -0,0 +1,89 @@
+/**
+ * Feature Spec Schema — Zod schema for feature spec YAML files.
+ *
+ * Analogous to the compression block in the book workflow:
+ * a structured, machine-readable spec for a single feature/ticket/PR that
+ * declares exactly which endpoints, models, and patterns are involved.
+ *
+ * Example feature spec file (feature-specs/auth-refresh.yaml):
+ *
+ *   feature: "JWT Refresh Token"
+ *   description: "Add refresh token rotation to the auth flow"
+ *   affected_endpoints:
+ *     - POST /api/auth/refresh
+ *     - POST /api/auth/logout
+ *   affected_models:
+ *     - RefreshToken
+ *     - Session
+ *   pattern: P2
+ *   tradeoff: "Security vs. UX: shorter-lived tokens mean more frequent refreshes"
+ *   failure_risk: "Token replay if refresh not rotated on use"
+ *   maps_to: "AuthService.rotate_refresh_token()"
+ *   sprint: 8
+ */
+import { z } from "zod";
+export const FeatureSpecSchema = z.object({
+    /** Short name of the feature — used as the context packet filename */
+    feature: z.string().min(1),
+    /** One or two sentence description of what this feature does */
+    description: z.string().default(""),
+    /**
+     * Endpoints this feature adds or modifies.
+     * Format: "METHOD /path" e.g. "POST /api/auth/refresh"
+     */
+    affected_endpoints: z.array(z.string()).default([]),
+    /**
+     * ORM models this feature reads from or writes to.
+     */
+    affected_models: z.array(z.string()).default([]),
+    /**
+     * Pattern ID(s) this feature uses (from the pattern registry).
+     * Single string or array: "P1" or ["P1", "P2"]
+     */
+    pattern: z
+        .union([z.string(), z.array(z.string())])
+        .transform((v) => (Array.isArray(v) ? v : [v]))
+        .default([]),
+    /**
+     * Architectural tradeoff involved (free text or AT-code if using DNCF series).
+     */
+    tradeoff: z.string().default(""),
+    /**
+     * Failure risk / failure mode to watch for.
+     */
+    failure_risk: z.string().default(""),
+    /**
+     * Primary service method or function this feature maps to.
+     * e.g. "AuthService.rotate_refresh_token()"
+     */
+    maps_to: z.string().default(""),
+    /**
+     * Sprint or version when this feature was / will be implemented.
+     * Used to build feature arc timelines.
+     */
+    sprint: z.union([z.number(), z.string()]).optional(),
+    /**
+     * Optional tags for grouping features (e.g. "auth", "billing", "core").
+     */
+    tags: z.array(z.string()).default([]),
+});
+/**
+ * Parse and validate a raw YAML-loaded object as a FeatureSpec.
+ * Throws a ZodError on invalid input.
+ */
+export function parseFeatureSpec(raw) {
+    return FeatureSpecSchema.parse(raw);
+}
+/**
+ * Safe parse — returns { success, data } without throwing.
+ */
+export function safeParseFeatureSpec(raw) {
+    const result = FeatureSpecSchema.safeParse(raw);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        error: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+    };
+}

package/dist/schema/index.js

@@ -0,0 +1,8 @@
+import { architectureSnapshotSchema } from "./architecture.js";
+import { uxSnapshotSchema } from "./ux.js";
+export function validateArchitectureSnapshot(snapshot) {
+    architectureSnapshotSchema.parse(snapshot);
+}
+export function validateUxSnapshot(snapshot) {
+    uxSnapshotSchema.parse(snapshot);
+}

package/dist/schema/ux.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+export const uxPageSummarySchema = z.object({
+    path: z.string(),
+    component: z.string(),
+    component_id: z.string(),
+    components: z.array(z.string()),
+    components_direct: z.array(z.string()),
+    components_descendants: z.array(z.string()),
+    components_direct_ids: z.array(z.string()),
+    components_descendants_ids: z.array(z.string()),
+    local_state_variables: z.array(z.string()),
+    api_calls: z.array(z.string()),
+    component_api_calls: z.array(z.object({
+        component: z.string(),
+        component_id: z.string(),
+        api_calls: z.array(z.string())
+    })),
+    component_state_variables: z.array(z.object({
+        component: z.string(),
+        component_id: z.string(),
+        local_state_variables: z.array(z.string())
+    })),
+    possible_navigation: z.array(z.string())
+});
+export const uxSnapshotSchema = z.object({
+    version: z.literal("0.2"),
+    components: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        file: z.string(),
+        kind: z.enum(["page", "component"]),
+        export_kind: z.enum(["default", "named"]),
+        props: z
+            .array(z.object({
+            name: z.string(),
+            type: z.string(),
+            optional: z.boolean()
+        }))
+            .optional()
+    })),
+    component_graph: z.array(z.object({
+        from: z.string(),
+        to: z.string()
+    })),
+    pages: z.array(uxPageSummarySchema)
+});

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@toolbaux/guardian",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Architectural intelligence for codebases. Verify that AI-generated code matches your architectural intent.",
+  "keywords": [
+    "architecture",
+    "ai",
+    "code-generation",
+    "drift",
+    "verification",
+    "guardian",
+    "specguard",
+    "ast",
+    "tree-sitter",
+    "claude",
+    "cursor",
+    "copilot"
+  ],
+  "license": "MIT",
+  "author": "Harish Kumar",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/idocoding/guardian"
+  },
+  "homepage": "https://github.com/idocoding/guardian#readme",
+  "bugs": {
+    "url": "https://github.com/idocoding/guardian/issues"
+  },
+  "bin": {
+    "guardian": "dist/cli.js",
+    "specguard": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:hallucination": "tsx scripts/test-hallucination-prevention.ts",
+    "benchmark:cto": "tsx scripts/cto-pitch-benchmark.ts",
+    "benchmark:llm": "tsx scripts/benchmark-llm-context/index.ts"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "dotenv": "^17.3.1",
+    "js-yaml": "^4.1.0",
+    "openai": "^6.32.0",
+    "tree-sitter": "^0.21.0",
+    "tree-sitter-c-sharp": "^0.21.1",
+    "tree-sitter-go": "^0.21.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "typescript": "^5.6.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.30",
+    "@vitest/coverage-v8": "^4.1.0",
+    "tsx": "^4.19.2",
+    "vitest": "^4.1.0"
+  }
+}