@trebired/code-discipline 1.5.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to `@trebired/code-discipline` will be documented here.
 
+## 2.1.0
+
+- Removed severity from the public rule config, violation objects, and result summaries.
+- Changed discipline and sync results to report `violationCount` instead of separate `errors` and `warnings`.
+- Simplified CLI output to concise violation lines and short summaries instead of JSON-style payloads.
+- Reduced logger noise by dropping large violation metadata from summary events and only emitting initialization logs when logging is enabled.
+
+## 2.0.0
+
+- Removed the top-level `code-discipline sync` command and the runtime `sync` / `startup` modes.
+- Changed the package-owned surface to `check` and `fix`, with positional rule selectors such as `code-discipline fix sync-imports`.
+- Changed config auto-discovery to the new `tb.code-discipline.*` filenames and added package-owned TypeScript config loading for Node and Bun.
+- Added the `dry` rule for canonical helper registration, duplicate detection, and full-removal standalone autofix.
+- Moved optional `package.json#imports` syncing under `rules.syncImports.packageJsonImports`.
+- Changed `fixCodeDiscipline()` from a folderization-only mutation path into a rule-ordered fix pipeline with `ruleResults`.
+
 ## 1.5.0
 
 - Added direct config auto-discovery so the CLI can be used as `code-discipline check`, `fix`, and `sync` without mandatory wrapper scripts or `--config` flags.

package/README.md

@@ -1,411 +1,305 @@
 # @trebired/code-discipline
 
-Configurable repository discipline checks, structural fixes, and import syncing for Bun and Node.js projects.
+Configurable repository discipline checks and rule-driven fixes for Bun and Node.js projects.
 
-`@trebired/code-discipline` is intentionally focused. It helps you keep a source tree disciplined without turning into a full linter, formatter, or build system.
+`@trebired/code-discipline` stays in one lane:
+
+- code shape rules such as max lines per file or function
+- structural rules such as folderizing compound files
+- sync rules such as keeping source imports, `tsconfig.json`, and optional `package.json#imports` aligned
+- DRY enforcement against registered canonical helper functions
+
+It is not a formatter, linter replacement, or build system.
 
 ## Install
 
-Runtime support: Bun 1+ and Node.js 18+.
+Runtime support:
+
+- Bun 1+
+- Node.js 18+
 
 ```sh
 npm install @trebired/code-discipline
 ```
 
-## Why This Package
-
-Some repository rules are not really single-file lint rules. They are about the shape of the tree:
-
-- files growing too large
-- functions growing too large
-- compound filenames that want to become folders
-- alias drift between `tsconfig.json` and source imports
-- returning structured policy results that a caller can interpret
-
-That is the lane of this package.
-
 ## Commands
 
 ```sh
 code-discipline check
-code-discipline sync
+code-discipline check max-function-lines dry
 code-discipline fix
+code-discipline fix sync-imports dry
 ```
 
-The CLI auto-discovers a config module in the current project root. Supported default names:
+Top-level `sync` is gone.
 
-- `discipline.config.mjs`
-- `discipline.config.js`
-- `discipline.config.cjs`
-- `code-discipline.config.mjs`
-- `code-discipline.config.js`
-- `code-discipline.config.cjs`
-
-You can still override discovery explicitly:
+`sync-imports` is now just another fixable rule, so targeted sync work is done through:
 
 ```sh
-code-discipline check --config ./discipline.config.mjs
+code-discipline fix sync-imports
 ```
 
-Typical `package.json` scripts can now stay direct and generic:
+Typical `package.json` scripts can stay simple:
 
 ```json
 {
   "scripts": {
     "discipline:check": "code-discipline check",
-    "discipline:fix": "code-discipline fix",
-    "discipline:sync": "code-discipline sync"
+    "discipline:fix": "code-discipline fix"
   }
 }
 ```
 
-Command responsibilities stay clean:
-
-- `check`: read-only validation and logging
-- `sync`: package-owned synchronization work from config
-- `fix`: configured structural fixes only
-
-Mutations stay opt-in:
+## Config
 
-- `syncImports` rewrites imports and `tsconfig.json` only when `syncImports.fix` is `true`
-- `runtimeImportsSync` updates `package.json#imports` only when that feature is enabled
-- `fix` applies folderization moves only when `folderizeCompoundFiles.fix` is `true`
+The CLI auto-discovers a top-level config module in this order:
 
-## Simple Runtime API
+- `tb.code-discipline.ts`
+- `tb.code-discipline.mts`
+- `tb.code-discipline.mjs`
+- `tb.code-discipline.js`
+- `tb.code-discipline.cts`
+- `tb.code-discipline.cjs`
 
-For app startup or scripts, you can now use one package-owned entrypoint instead of hand-rolling mode dispatch in app code.
+`tb.code-discipline.ts` is the recommended default.
 
-```ts
-import { codeDiscipline } from "@trebired/code-discipline";
+You can still point at an explicit module path:
 
-const result = await codeDiscipline({
-  mode: "check",
-  projectRoot: process.cwd(),
-  rules: {
-    maxFileLines: {
-      severity: "warning",
-      max: 500,
-    },
-    maxFunctionLines: {
-      severity: "warning",
-      max: 80,
-    },
-  },
-});
+```sh
+code-discipline check --config ./discipline.config.mjs
 ```
 
-`mode: "startup"` is a convenience alias for sync-oriented startup flows:
+Legacy config filenames are no longer auto-discovered, but they still work when passed explicitly with `--config`.
 
-```ts
-import { codeDiscipline } from "@trebired/code-discipline";
+Rules are enabled by presence. If a rule object exists under `rules`, it runs.
 
-await codeDiscipline({
-  mode: "startup",
-  projectRoot: PROJECT_ROOT,
-  logger,
-  rules: {
-    syncImports: {
-      severity: "error",
-      fix: true,
-      alias: {
-        strategy: "relative-path-slug",
-      },
-      allowRelative: ["./"],
-    },
-  },
-});
-```
-
-If you want to define repo rules once and reuse them, create a bound helper:
+Example `tb.code-discipline.ts`:
 
 ```ts
-import { createCodeDiscipline } from "@trebired/code-discipline";
+import { defineCodeDisciplineConfig } from "@trebired/code-discipline";
 
-const discipline = createCodeDiscipline({
-  sourceRoot: "src",
-  rules: {
-    syncImports: {
-      severity: "error",
-      fix: true,
-      alias: {
-        strategy: "relative-path-slug",
-      },
-      allowRelative: ["./"],
-    },
-  },
-});
-
-await discipline.startup({ projectRoot: PROJECT_ROOT, logger });
-process.exitCode = (await discipline.check({ projectRoot: process.cwd() })).ok ? 0 : 1;
-```
-
-## Config
-
-Rules are enabled by presence. If a rule object exists under `rules`, it runs. If the rule is omitted, it is disabled.
-
-`severity` is discipline metadata, not a logger level and not process control. The library never calls `process.exit()` from core APIs. Callers decide what to do with `ok`, `errors`, and `warnings`.
-
-Example config module:
-
-```js
-export default {
+export default defineCodeDisciplineConfig({
   sourceRoot: "src",
   sourceExtensions: [".ts", ".tsx", ".js", ".jsx"],
   excludeDirs: ["node_modules", "dist", ".vite"],
-  logging: {
-    enabled: true,
-    quiet: false,
-  },
   tsconfigPaths: {
     normalize: "relative-dot-prefix",
     restoreAfterRun: true,
   },
-  runtimeImportsSync: {
-    enabled: true,
-    source: "tsconfig.paths",
-    target: "package.json.imports",
-    aliasPrefix: "#",
-  },
   lifecycle: {
     async beforeRun(context) {
       context.state.started = true;
     },
-    async afterRun(context, result) {
-      context.state.finished = result.ok;
-    },
   },
   rules: {
     maxFileLines: {
-      severity: "warning",
       max: 500,
     },
     maxFunctionLines: {
-      severity: "warning",
       max: 80,
     },
     folderizeCompoundFiles: {
-      severity: "error",
       fix: true,
       separators: ["_", "-"],
     },
     syncImports: {
-      severity: "error",
       fix: true,
       alias: {
+        prefix: "#",
         strategy: "relative-path-slug",
       },
       allowRelative: ["./"],
+      packageJsonImports: {
+        enabled: true,
+        aliasPrefix: "#",
+      },
+    },
+    dry: {
+      fix: true,
+      helpers: [
+        {
+          from: "./src/shared/to-text.ts",
+          exportName: "toText",
+        },
+      ],
     },
   },
-};
+});
 ```
 
-## Generic Lifecycle Hooks
-
-If a project needs package-owned preprocessing or postprocessing around discipline commands, use config hooks instead of wrapper scripts.
-
-Available hooks:
+## Rule Selectors
 
-- `lifecycle.beforeRun(context)`
-- `lifecycle.afterRun(context, result)`
-- `lifecycle.beforeMode(context)`
-- `lifecycle.afterMode(context, result)`
+`check` and `fix` both accept positional rule selectors:
 
-The hook context includes:
-
-- `mode`
-- `projectRoot`
-- `configPath`
-- `config`
-- mutable `state`
-
-## Optional Tsconfig Path Normalization
+```sh
+code-discipline check max-file-lines max-function-lines
+code-discipline fix sync-imports dry
+```
 
-Use `tsconfigPaths` when a project needs temporary normalization of `compilerOptions.paths` before discipline runs.
+Rules use kebab-case public slugs:
 
-```js
-export default {
-  tsconfigPaths: {
-    normalize: "relative-dot-prefix",
-    restoreAfterRun: true,
-  },
-};
-```
+- `max-file-lines`
+- `max-function-lines`
+- `folderize-compound-files`
+- `sync-imports`
+- `dry`
 
-Supported normalization modes:
+`fix` only accepts fixable rules. Trying to run `code-discipline fix max-function-lines` fails clearly.
 
-- `"relative-dot-prefix"`: turns `src/x.ts` into `./src/x.ts`
-- `"strip-dot-prefix"`: turns `./src/x.ts` into `src/x.ts`
-- `"none"`: disables the helper
+## Runtime API
 
-`restoreAfterRun: true` restores the original `tsconfig.json` after read-oriented runs so the normalization can stay package-owned instead of living in shell wrappers.
+The package-owned runtime dispatcher now has two modes only:
 
-## Optional Package Imports Sync
+- `check`
+- `fix`
 
-Use `runtimeImportsSync` when a project wants `package.json#imports` mirrored from `tsconfig.compilerOptions.paths`.
+```ts
+import { codeDiscipline } from "@trebired/code-discipline";
 
-```js
-export default {
-  runtimeImportsSync: {
-    enabled: true,
-    source: "tsconfig.paths",
-    target: "package.json.imports",
-    aliasPrefix: "#",
+const result = await codeDiscipline({
+  mode: "fix",
+  projectRoot: process.cwd(),
+  onlyRules: ["sync-imports"],
+  rules: {
+    syncImports: {
+      fix: true,
+      alias: {
+        strategy: "relative-path-slug",
+      },
+    },
   },
-};
+});
 ```
 
-Behavior:
-
-- only aliases matching the configured prefix or prefixes are managed
-- unrelated existing `package.json#imports` entries are preserved
-- the feature runs through `code-discipline sync` and `mode: "sync"` / `mode: "startup"`
-
-## Checks
-
-`checkCodeDiscipline()` is read-only. It never moves files, rewrites imports, or updates `tsconfig.json`.
+You can also bind config once:
 
 ```ts
-import { checkCodeDiscipline } from "@trebired/code-discipline";
+import { createCodeDiscipline } from "@trebired/code-discipline";
 
-const result = await checkCodeDiscipline({
-  projectRoot: "/repo",
+const discipline = createCodeDiscipline({
+  sourceRoot: "src",
   rules: {
-    maxFileLines: {
-      severity: "warning",
-      max: 500,
-    },
     maxFunctionLines: {
-      severity: "warning",
       max: 80,
     },
-    folderizeCompoundFiles: {
-      severity: "error",
-      separators: ["_", "-"],
-    },
     syncImports: {
-      severity: "error",
-      fix: false,
+      fix: true,
       alias: {
         strategy: "relative-path-slug",
       },
-      allowRelative: ["./"],
     },
   },
 });
+
+await discipline.fix({
+  projectRoot: process.cwd(),
+  onlyRules: ["sync-imports"],
+});
 ```
 
-Result shape:
+Every violation is treated uniformly now. Results expose `ok`, `violationCount`, and `violations`, and the CLI prints concise rule/file/message lines instead of large JSON-style payloads.
 
-```ts
-type CodeDisciplineSeverity = "error" | "warning";
-
-type CodeDisciplineViolation = {
-  rule: "max-file-lines" | "max-function-lines" | "folderize-compound-files" | "sync-imports";
-  severity: CodeDisciplineSeverity;
-  fix: boolean;
-  filePath: string;
-  message: string;
-  details: Record<string, unknown>;
-  suggestedPath?: string;
-};
-
-type CodeDisciplineResult = {
-  ok: boolean;
-  errors: number;
-  warnings: number;
-  violations: CodeDisciplineViolation[];
-};
-```
+## Rules
 
-`ok` becomes `false` only when at least one returned violation has `severity: "error"`.
+### `maxFileLines`
 
-## Function Length
+Reports files whose total line count exceeds `max`.
 
-`maxFunctionLines` reports function-like declarations whose total span exceeds a configured limit.
+### `maxFunctionLines`
 
-- function declarations
-- function expressions
-- arrow functions
-- class methods
-- constructors
-- getters and setters
+Reports function-like declarations whose total span exceeds `max`.
 
-Violations include the function name when available, plus `startLine` and `endLine` details.
+### `folderizeCompoundFiles`
 
-## Folderization
+Detects flat compound names such as `user_route.ts` and can move them into structural folders such as `user/route.ts`.
 
-`folderizeCompoundFiles` is structural. It does not depend on configured suffix lists.
+### `syncImports`
 
-Same-directory groups:
+Validates and optionally fixes:
 
-```txt
-src/api/user_route.ts
-src/api/user_schema.ts
-src/api/user_controller.ts
-```
+- `tsconfig.compilerOptions.paths`
+- relative source imports that should become aliases
+- optional `package.json#imports` drift through `packageJsonImports`
 
-suggest:
+Example targeted CLI usage:
 
-```txt
-src/api/user/route.ts
-src/api/user/schema.ts
-src/api/user/controller.ts
+```sh
+code-discipline fix sync-imports
 ```
 
-Repeated folder-prefix files are also detected:
+### `dry`
 
-```txt
-src/api/user/user_route.ts
-```
+Registers canonical helper functions and reports exact normalized duplicates.
+
+The first version is intentionally conservative:
 
-suggests:
+- matching is exact normalized structure, not heuristic similarity
+- whitespace, comments, function names, and local identifier names do not matter
+- class/object methods are report-only
+- autofix only runs when the duplicate can be removed completely and replaced by a canonical import
 
-```txt
-src/api/user/route.ts
+Canonical helpers are registered by module export reference:
+
+```ts
+dry: {
+  fix: true,
+  helpers: [
+    {
+      from: "./src/shared/to-text.ts",
+      exportName: "toText",
+    },
+    {
+      from: "./src/shared/normalize.ts",
+      exportName: "default",
+    },
+  ],
+}
 ```
 
-`check` only reports these candidates.
+Supported canonical helper exports:
 
-`fix` may apply them only when `folderizeCompoundFiles.fix` is `true`, and it rewrites affected relative imports after the move.
+- exported function declarations
+- exported const bindings initialized with function expressions or arrow functions
+- default exports of those function shapes
 
-## Import Sync
+## Lifecycle Hooks
 
-`syncImports()` and `code-discipline sync` use the same severity-aware config shape.
+Hooks remain package-owned and generic:
 
-```ts
-import { syncImports } from "@trebired/code-discipline";
+- `beforeRun(context)`
+- `afterRun(context, result)`
+- `beforeMode(context)`
+- `afterMode(context, result)`
 
-const result = await syncImports({
-  projectRoot: "/repo",
-  severity: "error",
-  fix: true,
-  alias: {
-    strategy: "relative-path-slug",
-  },
-  allowRelative: ["./"],
-});
-```
+The hook context includes:
 
-Behavior:
+- `mode`
+- `projectRoot`
+- `configPath`
+- `config`
+- mutable `state`
 
-- `fix: false` reports alias/import drift as violations
-- `fix: true` rewrites imports and updates `tsconfig.json`
-- `allowRelative: ["./"]` keeps same-folder relative imports
-- upward relative imports can be reported or rewritten through the configured alias policy
+## Tsconfig Path Normalization
 
-`syncImports()` keeps its operational result fields and also returns `errors`, `warnings`, and `violations`.
+Use `tsconfigPaths` when a run needs temporary `compilerOptions.paths` normalization:
+
+```ts
+tsconfigPaths: {
+  normalize: "relative-dot-prefix",
+  restoreAfterRun: true,
+}
+```
 
-## Logging
+Available modes:
 
-When you provide a logger, discipline results are emitted through it. Trebired-style loggers are supported directly, and the package falls back safely when no logger is provided.
+- `"relative-dot-prefix"` turns `src/x.ts` into `./src/x.ts`
+- `"strip-dot-prefix"` turns `./src/x.ts` into `src/x.ts`
+- `"none"` leaves values unchanged
 
-The default/common logger adaptation path is powered by `@trebired/logger-adapter`, while `logging.adapter(event)` remains available when you want exact control over the emitted event shape.
+## Advanced Helpers
 
-## Public API
+Low-level helpers are still exported for advanced tooling:
 
-- `codeDiscipline()`
-- `createCodeDiscipline()`
 - `checkCodeDiscipline()`
 - `fixCodeDiscipline()`
 - `syncImports()`
@@ -416,4 +310,4 @@ The default/common logger adaptation path is powered by `@trebired/logger-adapte
 - `restoreTsconfigPaths()`
 - `syncPackageJsonImportsFromTsconfigPaths()`
 
-The package also exports the public TypeScript types for severity, rule config, results, violations, alias strategies, logging adapters, and source scan rows.
+`syncImports()` remains available as a lower-level helper, but the package CLI no longer exposes a separate `sync` command.

package/dist/checks/fix-folderization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fix-folderization.d.ts","sourceRoot":"","sources":["../../src/checks/fix-folderization.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,uBAAuB,EACvB,oCAAoC,EACrC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAO7E,KAAK,WAAW,GAAG;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,iBAAS,4BAA4B,CACnC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,oCAAoC,EAC7C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,uBAAuB,CAUzB;AAED,iBAAS,aAAa,CACpB,WAAW,EAAE,iBAAiB,EAAE,EAChC,OAAO,EAAE,oCAAoC,GAC5C;IAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAAC,UAAU,EAAE,uBAAuB,EAAE,CAAA;CAAE,CAqBjE;AAsKD,iBAAe,gBAAgB,CAC7B,WAAW,EAAE,iBAAiB,EAAE,EAChC,OAAO,EAAE,oCAAoC,EAC7C,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA6ElC;AAED,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"fix-folderization.d.ts","sourceRoot":"","sources":["../../src/checks/fix-folderization.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,uBAAuB,EACvB,oCAAoC,EACrC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAO7E,KAAK,WAAW,GAAG;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,iBAAS,4BAA4B,CACnC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,oCAAoC,EAC7C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,uBAAuB,CASzB;AAED,iBAAS,aAAa,CACpB,WAAW,EAAE,iBAAiB,EAAE,EAChC,OAAO,EAAE,oCAAoC,GAC5C;IAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAAC,UAAU,EAAE,uBAAuB,EAAE,CAAA;CAAE,CAqBjE;AAsKD,iBAAe,gBAAgB,CAC7B,WAAW,EAAE,iBAAiB,EAAE,EAChC,OAAO,EAAE,oCAAoC,EAC7C,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAwElC;AAED,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/checks/fix-folderization.js

@@ -8,7 +8,6 @@ import { planFolderizeCompoundFiles } from "./rules/folderize-plan.js";
 function createFolderizationViolation(filePath, suggestedPath, options, details) {
     return {
         rule: "folderize-compound-files",
-        severity: options.rules.folderizeCompoundFiles?.severity ?? "error",
         fix: options.rules.folderizeCompoundFiles?.fix ?? false,
         filePath,
         message: `file can be grouped under ${suggestedPath}`,
@@ -156,37 +155,32 @@ async function removeEmptyDirectories(directories) {
 }
 async function fixFolderization(sourceFiles, options, logger) {
     const { moves, violations } = buildMovePlan(sourceFiles, options);
-    const warnings = violations.filter((violation) => violation.severity === "warning").length;
-    const errors = violations.length - warnings;
     if (!options.rules.folderizeCompoundFiles || moves.length === 0) {
         logger.info("fix-folderization-unchanged", "no folderization moves required", {
             moves: 0,
         });
         return {
             ok: true,
-            errors: 0,
+            violationCount: 0,
             moved_files: 0,
             rewritten_files: 0,
             rewritten_imports: 0,
-            warnings,
+            ruleResults: {},
             violations: [],
         };
     }
     if (!options.rules.folderizeCompoundFiles.fix) {
         logger.warn("fix-folderization-disabled", "folderization fix is disabled", {
             candidates: moves.length,
-            discipline: {
-                errors,
-                warnings,
-            },
+            violationCount: violations.length,
         });
         return {
-            ok: errors === 0,
-            errors,
+            ok: false,
+            violationCount: violations.length,
             moved_files: 0,
             rewritten_files: 0,
             rewritten_imports: 0,
-            warnings,
+            ruleResults: {},
             violations,
         };
     }
@@ -206,11 +200,11 @@ async function fixFolderization(sourceFiles, options, logger) {
         });
         return {
             ok: true,
-            errors: 0,
+            violationCount: 0,
             moved_files: movedFiles,
             rewritten_files: rewriteState.rewrittenFiles,
             rewritten_imports: rewriteState.rewrittenImports,
-            warnings: 0,
+            ruleResults: {},
             violations: [],
         };
     }