@webpieces/rules-config 0.3.166 → 0.3.167

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.3.166",
+  "version": "0.3.167",
   "description": "Shared webpieces.config.json loader. Single source of truth for validation rule configuration consumed by @webpieces/ai-hook-rules, @webpieces/code-rules, and @webpieces/nx-webpieces-rules.",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/inform-ai-error.d.ts

@@ -1,3 +1,6 @@
 export declare class InformAiError extends Error {
-    constructor(message: string);
+    cause?: Error;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
 }

package/src/inform-ai-error.js

@@ -2,9 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InformAiError = void 0;
 class InformAiError extends Error {
-    constructor(message) {
+    cause;
+    constructor(message, options) {
         super(message);
         this.name = 'InformAiError';
+        this.cause = options?.cause;
     }
 }
 exports.InformAiError = InformAiError;

package/src/inform-ai-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"inform-ai-error.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/inform-ai-error.ts"],"names":[],"mappings":";;;AAAA,MAAa,aAAc,SAAQ,KAAK;IACpC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAChC,CAAC;CACJ;AALD,sCAKC","sourcesContent":["export class InformAiError extends Error {\n    constructor(message: string) {\n        super(message);\n        this.name = 'InformAiError';\n    }\n}\n"]}
+{"version":3,"file":"inform-ai-error.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/inform-ai-error.ts"],"names":[],"mappings":";;;AAAA,MAAa,aAAc,SAAQ,KAAK;IAC3B,KAAK,CAAS;IAEvB,YAAY,OAAe,EAAE,OAA2B;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAChC,CAAC;CACJ;AARD,sCAQC","sourcesContent":["export class InformAiError extends Error {\n    override cause?: Error;\n\n    constructor(message: string, options?: { cause?: Error }) {\n        super(message);\n        this.name = 'InformAiError';\n        this.cause = options?.cause;\n    }\n}\n"]}

package/src/types.js

@@ -16,6 +16,7 @@ exports.ResolvedConfig = exports.ResolvedRuleConfig = void 0;
  * removed in favor of this single, more flexible switch.)
  */
 class ResolvedRuleConfig {
+    options;
     constructor(options) {
         this.options = options;
     }
@@ -39,6 +40,10 @@ exports.ResolvedRuleConfig = ResolvedRuleConfig;
  * should treat that as "no validation configured").
  */
 class ResolvedConfig {
+    rules;
+    userConfiguredRuleNames;
+    rulesDir;
+    configPath;
     constructor(rules, userConfiguredRuleNames, rulesDir, configPath) {
         this.rules = rules;
         this.userConfiguredRuleNames = userConfiguredRuleNames;

package/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/types.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;GAaG;AACH,MAAa,kBAAkB;IAG3B,YAAY,OAAoB;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,oFAAoF;IACpF,IAAI,IAAI;QACJ,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjD,CAAC;IAED,iFAAiF;IACjF,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC;IAC/B,CAAC;CACJ;AAjBD,gDAiBC;AAED;;;;;;;GAOG;AACH,MAAa,cAAc;IAMvB,YACI,KAAsC,EACtC,uBAA4C,EAC5C,QAA2B,EAC3B,UAAyB;QAEzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,uBAAuB,GAAG,uBAAuB,CAAC;QACvD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;CACJ;AAjBD,wCAiBC","sourcesContent":["// webpieces-disable no-any-unknown -- rule options are opaque at framework level; each consumer casts internally\nexport type RuleOptions = Record<string, unknown>;\n\n/**\n * One rule entry from webpieces.config.json, merged with built-in defaults.\n *\n * `options` contains the raw option bag (mode, limit, disableAllowed,\n * ignoreModifiedUntilEpoch, enforcePaths, etc). Consumers extract the\n * fields they understand and ignore the rest.\n *\n * On/off is driven entirely by `mode`: a rule is OFF only when explicitly\n * set to `mode: \"OFF\"`. Any other value (or an absent mode) leaves the rule\n * ON. For code-rules, `mode` doubles as the scope selector\n * (e.g. \"MODIFIED_CODE\", \"NEW_AND_MODIFIED_METHODS\"); for simple on/off\n * rules it is just \"ON\"/\"OFF\". (The legacy `enabled` boolean has been\n * removed in favor of this single, more flexible switch.)\n */\nexport class ResolvedRuleConfig {\n    readonly options: RuleOptions;\n\n    constructor(options: RuleOptions) {\n        this.options = options;\n    }\n\n    /** Raw mode string from the option bag (\"ON\" | \"OFF\" | scope value), if present. */\n    get mode(): string | undefined {\n        const m = this.options['mode'];\n        return typeof m === 'string' ? m : undefined;\n    }\n\n    /** A rule is off only when explicitly `mode: \"OFF\"`. An absent mode means on. */\n    get isOff(): boolean {\n        return this.mode === 'OFF';\n    }\n}\n\n/**\n * The fully-resolved workspace configuration: every rule known to the\n * workspace (built-in + consumer overrides) keyed by its canonical\n * kebab-case name.\n *\n * `configPath` is null when no webpieces.config.json was found (loaders\n * should treat that as \"no validation configured\").\n */\nexport class ResolvedConfig {\n    readonly rules: Map<string, ResolvedRuleConfig>;\n    readonly userConfiguredRuleNames: ReadonlySet<string>;\n    readonly rulesDir: readonly string[];\n    readonly configPath: string | null;\n\n    constructor(\n        rules: Map<string, ResolvedRuleConfig>,\n        userConfiguredRuleNames: ReadonlySet<string>,\n        rulesDir: readonly string[],\n        configPath: string | null,\n    ) {\n        this.rules = rules;\n        this.userConfiguredRuleNames = userConfiguredRuleNames;\n        this.rulesDir = rulesDir;\n        this.configPath = configPath;\n    }\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/types.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;GAaG;AACH,MAAa,kBAAkB;IAClB,OAAO,CAAc;IAE9B,YAAY,OAAoB;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,oFAAoF;IACpF,IAAI,IAAI;QACJ,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjD,CAAC;IAED,iFAAiF;IACjF,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC;IAC/B,CAAC;CACJ;AAjBD,gDAiBC;AAED;;;;;;;GAOG;AACH,MAAa,cAAc;IACd,KAAK,CAAkC;IACvC,uBAAuB,CAAsB;IAC7C,QAAQ,CAAoB;IAC5B,UAAU,CAAgB;IAEnC,YACI,KAAsC,EACtC,uBAA4C,EAC5C,QAA2B,EAC3B,UAAyB;QAEzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,uBAAuB,GAAG,uBAAuB,CAAC;QACvD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;CACJ;AAjBD,wCAiBC","sourcesContent":["// webpieces-disable no-any-unknown -- rule options are opaque at framework level; each consumer casts internally\nexport type RuleOptions = Record<string, unknown>;\n\n/**\n * One rule entry from webpieces.config.json, merged with built-in defaults.\n *\n * `options` contains the raw option bag (mode, limit, disableAllowed,\n * ignoreModifiedUntilEpoch, enforcePaths, etc). Consumers extract the\n * fields they understand and ignore the rest.\n *\n * On/off is driven entirely by `mode`: a rule is OFF only when explicitly\n * set to `mode: \"OFF\"`. Any other value (or an absent mode) leaves the rule\n * ON. For code-rules, `mode` doubles as the scope selector\n * (e.g. \"MODIFIED_CODE\", \"NEW_AND_MODIFIED_METHODS\"); for simple on/off\n * rules it is just \"ON\"/\"OFF\". (The legacy `enabled` boolean has been\n * removed in favor of this single, more flexible switch.)\n */\nexport class ResolvedRuleConfig {\n    readonly options: RuleOptions;\n\n    constructor(options: RuleOptions) {\n        this.options = options;\n    }\n\n    /** Raw mode string from the option bag (\"ON\" | \"OFF\" | scope value), if present. */\n    get mode(): string | undefined {\n        const m = this.options['mode'];\n        return typeof m === 'string' ? m : undefined;\n    }\n\n    /** A rule is off only when explicitly `mode: \"OFF\"`. An absent mode means on. */\n    get isOff(): boolean {\n        return this.mode === 'OFF';\n    }\n}\n\n/**\n * The fully-resolved workspace configuration: every rule known to the\n * workspace (built-in + consumer overrides) keyed by its canonical\n * kebab-case name.\n *\n * `configPath` is null when no webpieces.config.json was found (loaders\n * should treat that as \"no validation configured\").\n */\nexport class ResolvedConfig {\n    readonly rules: Map<string, ResolvedRuleConfig>;\n    readonly userConfiguredRuleNames: ReadonlySet<string>;\n    readonly rulesDir: readonly string[];\n    readonly configPath: string | null;\n\n    constructor(\n        rules: Map<string, ResolvedRuleConfig>,\n        userConfiguredRuleNames: ReadonlySet<string>,\n        rulesDir: readonly string[],\n        configPath: string | null,\n    ) {\n        this.rules = rules;\n        this.userConfiguredRuleNames = userConfiguredRuleNames;\n        this.rulesDir = rulesDir;\n        this.configPath = configPath;\n    }\n}\n"]}

package/templates/webpieces.exceptions.md

@@ -671,6 +671,51 @@ If you believe you have a legitimate use case for try-catch:
 
 4. **Be prepared to justify** - 99% of try-catch can be removed
 
+## Rule: throw-cause-required
+
+When you catch an exception and rethrow with additional context, you MUST chain the original
+exception using `{ cause: error }`. Embedding `error.message` in a string loses the original
+stack trace and is banned.
+
+### BAD (triggers violation)
+```typescript
+} catch (err: unknown) {
+  const error = toError(err);
+  throw new InformAiError(`Cannot load config: ${error.message}`);  // ← BANNED
+}
+```
+
+### Why it's bad
+The original stack trace is gone. Debugging tools only see the new error; the root cause
+and its call stack have been discarded.
+
+### Fix Options
+
+**Option 1 — Remove the try-catch (usually best)**
+```typescript
+// Just let it bubble — the global handler logs it with full context
+const config = JSON.parse(raw);
+```
+
+**Option 2 — Rethrow with cause (generic)**
+```typescript
+} catch (err: unknown) {
+  const error = toError(err);
+  throw new Error(`Cannot load config`, { cause: error });
+}
+```
+
+**Option 3 — Rethrow with specific error class + cause**
+```typescript
+} catch (err: unknown) {
+  const error = toError(err);
+  throw new InformAiError(`Cannot load config — fix the JSON then retry`, { cause: error });
+}
+```
+
+The `cause` field is available on the original error object and will appear in stack traces
+and in `/debugLocal/{traceId}` responses.
+
 ## Summary
 
 **The webpieces philosophy**: Errors should bubble to the global handler where they are logged with traceId and stored for debugging. Local try-catch blocks break this architecture and create blind spots in production.