@lifesavertech/archguard-guidance 2.0.0

package/README.md

@@ -0,0 +1,9 @@
+# @lifesavertech/archguard-guidance
+
+Generates `AGENTS.md` and `.archguard/ARCHITECTURE_RULES.md` from `architecture.yaml`.
+
+Most users should install `@lifesavertech/archguard-cli` rather than depending on this package directly.
+
+v2.2 will add `archguard sync` to keep guidance files aligned with config.
+
+Documentation: [github.com/lindseystead/ArchGuard](https://github.com/lindseystead/ArchGuard)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** Generates project-facing guidance files from the architecture config. */
+import { ArchitectureConfig } from "@lifesavertech/archguard-core";
+export declare function generateEditorGuide(architecture: ArchitectureConfig): string;
+export declare function generateAgentsGuide(architecture: ArchitectureConfig): string;

package/dist/index.js

@@ -0,0 +1,102 @@
+"use strict";
+/** Generates project-facing guidance files from the architecture config. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEditorGuide = generateEditorGuide;
+exports.generateAgentsGuide = generateAgentsGuide;
+const archguard_core_1 = require("@lifesavertech/archguard-core");
+function generateEditorGuide(architecture) {
+    const layerDescriptions = buildLayerDescriptions(architecture);
+    const rules = buildRuleDescriptions(architecture);
+    return `# Architecture Rules
+
+This repository uses ArchGuard to enforce architectural boundaries. Treat these rules as hard constraints.
+
+## Layer Structure
+
+${layerDescriptions}
+
+${buildUiLayerDescription(architecture)}
+
+## Rules
+
+${rules.join("\n")}
+
+## General Guidelines
+
+- **Do not create new folders** without explicit justification
+- **Do not merge layers** or blur boundaries
+- **Refactor violating code** instead of suppressing the rule
+- **Escalate architecture questions** before introducing a new dependency shape
+
+## When a Proposed Change Violates the Rules
+
+If a proposed change violates these rules:
+1. Read the violation message carefully.
+2. Move the logic or dependency to the correct layer.
+3. Avoid suppressing or bypassing the rule.
+4. Document any intentional exception before changing the architecture.
+
+Code should conform to the existing architecture unless the architecture is explicitly revised.
+`;
+}
+function generateAgentsGuide(architecture) {
+    const layerDescriptions = buildLayerDescriptions(architecture);
+    const rules = buildRuleDescriptions(architecture);
+    return `# AGENTS.md
+
+This repository uses ArchGuard for architecture enforcement. Follow these constraints when proposing or editing code.
+
+## Architecture
+
+${layerDescriptions}
+
+${buildUiLayerDescription(architecture)}
+
+## Required Constraints
+
+${rules.join("\n")}
+
+## Working Rules
+
+- Keep the existing folder structure unless a structural change is explicitly requested.
+- Do not bypass architectural violations by moving logic into a disallowed layer.
+- Prefer refactoring code into an allowed layer over introducing exceptions.
+- If the architecture needs to change, update \`architecture.yaml\` first and then regenerate supporting documents.
+
+## Enforcement
+
+These instructions are reference material for tooling and contributors. The enforceable source of truth is \`architecture.yaml\`, and validation happens through the ArchGuard CLI.
+`;
+}
+function buildLayerDescriptions(architecture) {
+    return Object.keys(architecture.layers)
+        .map((layer) => {
+        const config = architecture.layers[layer];
+        const allowed = config.allowedImports.length > 0 ? config.allowedImports.join(", ") : "none";
+        return `- **${layer}**: Can import from: ${allowed}`;
+    })
+        .join("\n");
+}
+function buildRuleDescriptions(architecture) {
+    const rules = [];
+    if (architecture.rules.noBusinessLogicInComponents) {
+        rules.push("- **No business logic in components**: React components must not contain loops, complex conditionals, calculations, or data transformations. Extract these to the feature or domain layer.");
+    }
+    if (architecture.rules.noDataFetchingInUI) {
+        rules.push("- **No data fetching in UI**: UI layer components must not call fetch/axios/query hooks directly or invoke imported domain/data-access helpers. Move data access to the features layer.");
+    }
+    if ((0, archguard_core_1.isLayerBoundaryEnforcementEnabled)(architecture.rules)) {
+        rules.push("- **Enforce layer boundaries**: Respect the layer import rules. Do not create imports that violate the defined architecture.");
+    }
+    if (architecture.rules.noCircularLayerDeps) {
+        rules.push("- **No circular dependencies**: Do not create circular dependencies between layers.");
+    }
+    return rules;
+}
+function buildUiLayerDescription(architecture) {
+    const uiLayers = Array.from((0, archguard_core_1.resolveUiLayers)(architecture));
+    if (uiLayers.length === 0) {
+        return "";
+    }
+    return `## UI Layers\n\nReact UI behavior rules apply to files in: ${uiLayers.join(", ")}.\n`;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lifesavertech/archguard-guidance",
+  "version": "2.0.0",
+  "description": "Project guidance document generator for ArchGuard",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "archguard",
+    "architecture",
+    "guidance"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -b --force",
+    "prepack": "npm run build",
+    "build:test": "node -e \"require('fs').rmSync('dist-test',{recursive:true,force:true})\" && tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test dist-test/index.test.js"
+  },
+  "dependencies": {
+    "@lifesavertech/archguard-core": "2.0.0",
+    "yaml": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "author": "Lindsey Stead",
+  "homepage": "https://github.com/lindseystead/ArchGuard#readme",
+  "bugs": {
+    "url": "https://github.com/lindseystead/ArchGuard/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lindseystead/ArchGuard.git",
+    "directory": "packages/guidance"
+  }
+}