@prover-coder-ai/context-doc 1.0.11 → 1.0.13

package/.jscpd.json

@@ -0,0 +1,16 @@
+{
+	"threshold": 0,
+	"minTokens": 30,
+	"minLines": 5,
+	"ignore": [
+		"**/node_modules/**",
+		"**/build/**",
+		"**/dist/**",
+		"**/*.min.js",
+		"**/reports/**"
+	],
+	"skipComments": true,
+	"ignorePattern": [
+		"private readonly \\w+: \\w+;\\s*private readonly \\w+: \\w+;\\s*private \\w+: \\w+ \\| null = null;\\s*private \\w+: \\w+ \\| null = null;"
+	]
+}

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @prover-coder-ai/context-doc
+
+## 1.0.13
+
+### Patch Changes
+
+- chore: automated version bump
+
+## 1.0.1
+
+### Patch Changes
+
+- chore: automated version bump

package/bin/context-doc.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// CHANGE: add a shebang CLI shim for npx execution
+// WHY: npx needs an executable entry that invokes the built main module
+// QUOTE(TZ): "Только вызов нашего пакета должен быть"
+// REF: user-2026-01-19-npx-check
+// SOURCE: n/a
+// FORMAT THEOREM: forall env: exec(bin) -> runMain(program)
+// PURITY: SHELL
+// EFFECT: Effect<void, never, RuntimeEnv | FileSystemService | CryptoService | Path>
+// INVARIANT: built main module is executed exactly once per invocation
+// COMPLEXITY: O(1)/O(1)
+import "../dist/main.js"

package/biome.json

@@ -0,0 +1,37 @@
+{
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": false,
+		"indentStyle": "tab"
+	},
+	"assist": {
+		"actions": {
+			"source": {
+				"organizeImports": "off"
+			}
+		}
+	},
+	"linter": {
+		"enabled": false,
+		"rules": {
+			"recommended": false,
+			"suspicious": {
+				"noExplicitAny": "off"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"enabled": false,
+			"quoteStyle": "double",
+			"semicolons": "asNeeded"
+		}
+	}
+}

package/eslint.config.mts

@@ -0,0 +1,305 @@
+// eslint.config.mjs
+// @ts-check
+import eslint from '@eslint/js';
+import { defineConfig } from 'eslint/config';
+import tseslint from 'typescript-eslint';
+import vitest from "@vitest/eslint-plugin";
+import suggestMembers from "@prover-coder-ai/eslint-plugin-suggest-members";
+import sonarjs from "eslint-plugin-sonarjs";
+import unicorn from "eslint-plugin-unicorn";
+import * as effectEslint from "@effect/eslint-plugin";
+import { fixupPluginRules } from "@eslint/compat";
+import codegen from "eslint-plugin-codegen";
+import importPlugin from "eslint-plugin-import";
+import simpleImportSort from "eslint-plugin-simple-import-sort";
+import sortDestructureKeys from "eslint-plugin-sort-destructure-keys";
+import globals from "globals";
+import eslintCommentsConfigs from "@eslint-community/eslint-plugin-eslint-comments/configs";
+
+const codegenPlugin = fixupPluginRules(
+	codegen as unknown as Parameters<typeof fixupPluginRules>[0],
+);
+
+const noFetchExample = [
+	"Пример:",
+	"  import { FetchHttpClient, HttpClient } from \"@effect/platform\"",
+	"  import { Effect } from \"effect\"",
+	"  const program = Effect.gen(function* () {",
+	"    const client = yield* HttpClient.HttpClient",
+	"    return yield* client.get(`${api}/robots`)",
+	"  }).pipe(",
+	"    Effect.scoped,",
+	"    Effect.provide(FetchHttpClient.layer)",
+	"  )",
+].join("\n");
+
+export default defineConfig(
+  eslint.configs.recommended,
+  tseslint.configs.strictTypeChecked,
+  effectEslint.configs.dprint,
+  suggestMembers.configs.recommended,
+  eslintCommentsConfigs.recommended,
+  {
+    name: "analyzers",
+    languageOptions: {
+      parser: tseslint.parser,
+	  globals: { ...globals.node, ...globals.browser },
+      parserOptions: {
+        projectService: true,          
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+	plugins: {
+		sonarjs,
+		unicorn,
+		import: fixupPluginRules(importPlugin),
+		"sort-destructure-keys": sortDestructureKeys,
+		"simple-import-sort": simpleImportSort,
+		codegen: codegenPlugin,
+	},
+	files: ["**/*.ts", '**/*.{test,spec}.{ts,tsx}', '**/tests/**', '**/__tests__/**'],
+	settings: {
+		"import/parsers": {
+			"@typescript-eslint/parser": [".ts", ".tsx"],
+		},
+		"import/resolver": {
+			typescript: {
+				alwaysTryTypes: true,
+			},
+		},
+	},
+	rules: {
+		...sonarjs.configs.recommended.rules,
+		...unicorn.configs.recommended.rules,
+		"no-restricted-imports": ["error", {
+			paths: [
+				{
+					name: "ts-pattern",
+					message: "Use Effect.Match instead of ts-pattern.",
+				},
+				{
+					name: "zod",
+					message: "Use @effect/schema for schemas and validation.",
+				},
+			],
+		}],
+		"codegen/codegen": "error",
+		"import/first": "error",
+		"import/newline-after-import": "error",
+		"import/no-duplicates": "error",
+		"import/no-unresolved": "off",
+		"import/order": "off",
+		"simple-import-sort/imports": "off",
+		"sort-destructure-keys/sort-destructure-keys": "error",
+		"no-fallthrough": "off",
+		"no-irregular-whitespace": "off",
+		"object-shorthand": "error",
+		"prefer-destructuring": "off",
+		"sort-imports": "off",
+		"no-unused-vars": "off",
+		"prefer-rest-params": "off",
+		"prefer-spread": "off",
+		"unicorn/prefer-top-level-await": "off",
+		"unicorn/prevent-abbreviations": "off",
+		"unicorn/no-null": "off",
+		complexity: ["error", 8],
+		"max-lines-per-function": [
+			"error",
+			{ max: 50, skipBlankLines: true, skipComments: true },
+		],
+		"max-params": ["error", 5],
+		"max-depth": ["error", 4],
+		"max-lines": [
+			"error",
+			{ max: 300, skipBlankLines: true, skipComments: true },
+		],
+
+		"@typescript-eslint/restrict-template-expressions": ["error", {
+			allowNumber: true,
+			allowBoolean: true,
+			allowNullish: false,
+			allowAny: false,
+			allowRegExp: false
+		}],
+		"@eslint-community/eslint-comments/no-use": "error",
+		"@eslint-community/eslint-comments/no-unlimited-disable": "error",
+		"@eslint-community/eslint-comments/disable-enable-pair": "error",
+		"@eslint-community/eslint-comments/no-unused-disable": "error",
+		"no-restricted-syntax": [
+				"error",
+				{
+					selector: "TSUnknownKeyword",
+					message: "Запрещено 'unknown'.",
+				},
+				// CHANGE: запрет прямого fetch в коде
+				// WHY: enforce Effect-TS httpClient as единственный источник сетевых эффектов
+				// QUOTE(ТЗ): "Вместо fetch должно быть всегда написано httpClient от библиотеки Effect-TS"
+				// REF: user-msg-1
+				// SOURCE: n/a
+				// FORMAT THEOREM: ∀call ∈ Calls: callee(call)=fetch → lint_error(call)
+				// PURITY: SHELL
+				// EFFECT: Effect<never, never, never>
+				// INVARIANT: direct fetch calls are forbidden
+				// COMPLEXITY: O(1)
+				{
+					selector: "CallExpression[callee.name='fetch']",
+					message: `Запрещён fetch — используй HttpClient (Effect-TS).\n${noFetchExample}`,
+				},
+				{
+					selector:
+						"CallExpression[callee.object.name='window'][callee.property.name='fetch']",
+					message: `Запрещён window.fetch — используй HttpClient (Effect-TS).\n${noFetchExample}`,
+				},
+				{
+					selector:
+						"CallExpression[callee.object.name='globalThis'][callee.property.name='fetch']",
+					message: `Запрещён globalThis.fetch — используй HttpClient (Effect-TS).\n${noFetchExample}`,
+				},
+				{
+					selector:
+						"CallExpression[callee.object.name='self'][callee.property.name='fetch']",
+					message: `Запрещён self.fetch — используй HttpClient (Effect-TS).\n${noFetchExample}`,
+				},
+				{
+					selector:
+						"CallExpression[callee.object.name='global'][callee.property.name='fetch']",
+					message: `Запрещён global.fetch — используй HttpClient (Effect-TS).\n${noFetchExample}`,
+				},
+				{
+					selector: "TryStatement",
+					message: "Используй Effect.try / catchAll вместо try/catch в core/app/domain.",
+				},
+				{
+					selector: "SwitchStatement",
+					message: [
+						"Switch statements are forbidden in functional programming paradigm.",
+						"How to fix: Use Effect.Match instead.",
+						"Example:",
+						"  import { Match } from 'effect';",
+						"  type Item = { type: 'this' } | { type: 'that' };",
+						"  const result = Match.value(item).pipe(",
+						"    Match.when({ type: 'this' }, (it) => processThis(it)),",
+						"    Match.when({ type: 'that' }, (it) => processThat(it)),",
+						"    Match.exhaustive,",
+						"  );",
+					].join("\n"),
+				},
+				{
+					selector: 'CallExpression[callee.name="require"]',
+					message: "Avoid using require(). Use ES6 imports instead.",
+				},
+				{
+					selector: "ThrowStatement > Literal:not([value=/^\\w+Error:/])",
+					message:
+						'Do not throw string literals or non-Error objects. Throw new Error("...") instead.',
+				},
+				{
+					selector:
+						"FunctionDeclaration[async=true], FunctionExpression[async=true], ArrowFunctionExpression[async=true]",
+					message:
+						"Запрещён async/await — используй Effect.gen / Effect.tryPromise.",
+				},
+				{
+					selector: "NewExpression[callee.name='Promise']",
+					message:
+						"Запрещён new Promise — используй Effect.async / Effect.tryPromise.",
+				},
+				{
+					selector: "CallExpression[callee.object.name='Promise']",
+					message:
+						"Запрещены Promise.* — используй комбинаторы Effect (all, forEach, etc.).",
+				},
+				{
+					selector: "CallExpression[callee.property.name='push'] > SpreadElement.arguments",
+					message: "Do not use spread arguments in Array.push",
+				},
+		],
+		"no-throw-literal": "error",
+		"@typescript-eslint/no-restricted-types": [
+				"error",
+				{
+					types: {
+						unknown: {
+							message:
+								"Не используем 'unknown'. Уточни тип или наведи порядок в источнике данных.",
+						},
+						Promise: {
+							message: "Запрещён Promise — используй Effect.Effect<A, E, R>.",
+							suggest: ["Effect.Effect"],
+						},
+						"Promise<*>": {
+							message:
+								"Запрещён Promise<T> — используй Effect.Effect<T, E, R>.",
+							suggest: ["Effect.Effect<T, E, R>"],
+						},
+					},
+				},
+			],
+		"@typescript-eslint/use-unknown-in-catch-callback-variable": "off",
+		// "no-throw-literal": "off",
+		"@typescript-eslint/only-throw-error": [
+			"error",
+			{ allowThrowingUnknown: false, allowThrowingAny: false },
+		],
+		"@typescript-eslint/array-type": ["warn", {
+			default: "generic",
+			readonly: "generic"
+		}],
+		"@typescript-eslint/member-delimiter-style": 0,
+		"@typescript-eslint/no-non-null-assertion": "off",
+		"@typescript-eslint/ban-types": "off",
+		"@typescript-eslint/no-explicit-any": "off",
+		"@typescript-eslint/no-empty-interface": "off",
+		"@typescript-eslint/consistent-type-imports": "warn",
+		"@typescript-eslint/no-unused-vars": ["error", {
+			argsIgnorePattern: "^_",
+			varsIgnorePattern: "^_"
+		}],
+		"@typescript-eslint/ban-ts-comment": "off",
+		"@typescript-eslint/camelcase": "off",
+		"@typescript-eslint/explicit-function-return-type": "off",
+		"@typescript-eslint/explicit-module-boundary-types": "off",
+		"@typescript-eslint/interface-name-prefix": "off",
+		"@typescript-eslint/no-array-constructor": "off",
+		"@typescript-eslint/no-use-before-define": "off",
+		"@typescript-eslint/no-namespace": "off",
+		"@effect/dprint": ["error", {
+			config: {
+				indentWidth: 2,
+				lineWidth: 120,
+				semiColons: "asi",
+				quoteStyle: "alwaysDouble",
+				trailingCommas: "never",
+				operatorPosition: "maintain",
+				"arrowFunction.useParentheses": "force"
+			}
+		}]
+	}
+  },
+  {
+    files: ['**/*.{test,spec}.{ts,tsx}', 'tests/**', '**/__tests__/**'],
+    ...vitest.configs.all,
+    languageOptions: {
+      globals: {
+        ...vitest.environments.env.globals,
+      },
+    },
+    rules: {
+      // Allow eslint-disable/enable comments in test files for fine-grained control
+      '@eslint-community/eslint-comments/no-use': 'off',
+      // Disable line count limit for E2E tests that contain multiple test cases
+      'max-lines-per-function': 'off',
+      // `it.effect` is not recognized by sonar rule; disable to avoid false positives
+      'sonarjs/no-empty-test-file': 'off',
+    },
+  },
+
+  // 3) Для JS-файлов отключим типо-зависимые проверки
+  {
+    files: ['**/*.{js,cjs,mjs}'],
+    extends: [tseslint.configs.disableTypeChecked],
+  },
+
+  // 4) Глобальные игноры
+  { ignores: ['dist/**', 'build/**', 'coverage/**', '**/dist/**'] },
+);

package/eslint.effect-ts-check.config.mjs

@@ -0,0 +1,220 @@
+// CHANGE: add Effect-TS compliance lint profile
+// WHY: detect current deviations from strict Effect-TS guidance
+// QUOTE(TZ): n/a
+// REF: AGENTS.md Effect-TS compliance checks
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: eslint config
+// INVARIANT: config only flags explicit policy deviations
+// COMPLEXITY: O(1)/O(1)
+import eslintComments from "@eslint-community/eslint-plugin-eslint-comments"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+const restrictedImports = [
+  {
+    name: "node:fs",
+    message: "Use @effect/platform FileSystem instead of node:fs."
+  },
+  {
+    name: "fs",
+    message: "Use @effect/platform FileSystem instead of fs."
+  },
+  {
+    name: "node:fs/promises",
+    message: "Use @effect/platform FileSystem instead of node:fs/promises."
+  },
+  {
+    name: "node:path/posix",
+    message: "Use @effect/platform Path instead of node:path/posix."
+  },
+  {
+    name: "node:path",
+    message: "Use @effect/platform Path instead of node:path."
+  },
+  {
+    name: "path",
+    message: "Use @effect/platform Path instead of path."
+  },
+  {
+    name: "node:child_process",
+    message: "Use @effect/platform Command instead of node:child_process."
+  },
+  {
+    name: "child_process",
+    message: "Use @effect/platform Command instead of child_process."
+  },
+  {
+    name: "node:process",
+    message: "Use @effect/platform Runtime instead of node:process."
+  },
+  {
+    name: "process",
+    message: "Use @effect/platform Runtime instead of process."
+  }
+]
+
+const restrictedSyntaxBase = [
+  {
+    selector: "SwitchStatement",
+    message: "Switch is forbidden. Use Match.exhaustive."
+  },
+  {
+    selector: "TryStatement",
+    message: "Avoid try/catch in product code. Use Effect.try / Effect.catch*."
+  },
+  {
+    selector: "AwaitExpression",
+    message: "Avoid await. Use Effect.gen / Effect.flatMap."
+  },
+  {
+    selector: "FunctionDeclaration[async=true], FunctionExpression[async=true], ArrowFunctionExpression[async=true]",
+    message: "Avoid async/await. Use Effect.gen / Effect.tryPromise."
+  },
+  {
+    selector: "NewExpression[callee.name='Promise']",
+    message: "Avoid new Promise. Use Effect.async / Effect.tryPromise."
+  },
+  {
+    selector: "CallExpression[callee.object.name='Promise']",
+    message: "Avoid Promise.*. Use Effect combinators."
+  },
+  {
+    selector: "CallExpression[callee.name='require']",
+    message: "Avoid require(). Use ES module imports."
+  },
+  {
+    selector: "TSAsExpression",
+    message: "Casting is only allowed in src/core/axioms.ts."
+  },
+  {
+    selector: "TSTypeAssertion",
+    message: "Casting is only allowed in src/core/axioms.ts."
+  },
+  {
+    selector: "CallExpression[callee.name='makeFilesystemService']",
+    message: "Do not instantiate FilesystemService directly. Provide Layer and access via Tag."
+  },
+  {
+    selector: "CallExpression[callee.property.name='catchAll']",
+    message: "Avoid catchAll that discards typed errors; map or propagate explicitly."
+  }
+]
+
+const restrictedSyntaxCore = [
+  ...restrictedSyntaxBase,
+  {
+    selector: "TSUnknownKeyword",
+    message: "unknown is allowed only at shell boundaries with decoding."
+  },
+  {
+    selector: "CallExpression[callee.property.name='runSyncExit']",
+    message: "Effect.runSyncExit is shell-only. Move to a runner."
+  },
+  {
+    selector: "CallExpression[callee.property.name='runSync']",
+    message: "Effect.runSync is shell-only. Move to a runner."
+  },
+  {
+    selector: "CallExpression[callee.property.name='runPromise']",
+    message: "Effect.runPromise is shell-only. Move to a runner."
+  }
+]
+
+const restrictedSyntaxCoreNoAs = [
+  ...restrictedSyntaxCore.filter((rule) =>
+    rule.selector !== "TSAsExpression" && rule.selector !== "TSTypeAssertion"
+  )
+]
+
+const restrictedSyntaxBaseNoServiceFactory = [
+  ...restrictedSyntaxBase.filter((rule) =>
+    rule.selector !== "CallExpression[callee.name='makeFilesystemService']"
+  )
+]
+
+export default tseslint.config(
+  {
+    name: "effect-ts-compliance-check",
+    files: ["src/**/*.ts", "scripts/**/*.ts"],
+    languageOptions: {
+      parser: tseslint.parser,
+      globals: { ...globals.node }
+    },
+    plugins: {
+      "@typescript-eslint": tseslint.plugin,
+      "eslint-comments": eslintComments
+    },
+    rules: {
+      "no-console": "error",
+      "no-restricted-imports": ["error", {
+        paths: restrictedImports,
+        patterns: [
+          {
+            group: ["node:*"],
+            message: "Do not import from node:* directly. Use @effect/platform-node or @effect/platform services."
+          }
+        ]
+      }],
+      "no-restricted-syntax": ["error", ...restrictedSyntaxBase],
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/ban-ts-comment": ["error", {
+        "ts-ignore": true,
+        "ts-nocheck": true,
+        "ts-check": false,
+        "ts-expect-error": true
+      }],
+      "@typescript-eslint/no-restricted-types": ["error", {
+        types: {
+          Promise: {
+            message: "Avoid Promise in types. Use Effect.Effect<A, E, R>."
+          },
+          "Promise<*>": {
+            message: "Avoid Promise<T>. Use Effect.Effect<T, E, R>."
+          }
+        }
+      }],
+      "eslint-comments/no-use": "error",
+      "eslint-comments/no-unlimited-disable": "error",
+      "eslint-comments/disable-enable-pair": "error",
+      "eslint-comments/no-unused-disable": "error"
+    }
+  },
+  {
+    name: "effect-ts-compliance-core",
+    files: ["src/core/**/*.ts"],
+    rules: {
+      "no-restricted-syntax": ["error", ...restrictedSyntaxCore],
+      "no-restricted-imports": ["error", {
+        paths: restrictedImports,
+        patterns: [
+          {
+            group: [
+              "../shell/**",
+              "../../shell/**",
+              "../../../shell/**",
+              "./shell/**",
+              "src/shell/**",
+              "shell/**"
+            ],
+            message: "CORE must not import from SHELL."
+          }
+        ]
+      }]
+    }
+  },
+  {
+    name: "effect-ts-compliance-axioms",
+    files: ["src/core/axioms.ts"],
+    rules: {
+      "no-restricted-syntax": ["error", ...restrictedSyntaxCoreNoAs]
+    }
+  },
+  {
+    name: "effect-ts-compliance-filesystem-service",
+    files: ["src/shell/services/filesystem.ts"],
+    rules: {
+      "no-restricted-syntax": ["error", ...restrictedSyntaxBaseNoServiceFactory]
+    }
+  }
+)

package/linter.config.json

@@ -0,0 +1,33 @@
+{
+	"priorityLevels": [
+		{
+			"level": 1,
+			"name": "Critical Compiler Errors",
+			"rules": [
+				"ts(2835)",
+				"ts(2307)",
+				"@prover-coder-ai/suggest-members/suggest-members",
+				"@prover-coder-ai/suggest-members/suggest-imports",
+				"@prover-coder-ai/suggest-members/suggest-module-paths",
+				"@prover-coder-ai/suggest-members/suggest-exports",
+				"@prover-coder-ai/suggest-members/suggest-missing-names",
+				"@typescript-eslint/no-explicit-any"
+			]
+		},
+		{
+			"level": 2,
+			"name": "Critical Compiler Errors",
+			"rules": ["all"]
+		},
+		{
+			"level": 3,
+			"name": "Critical Compiler Errors (Code must follow Clean Code and best practices)",
+			"rules": ["max-lines-per-function", "max-lines"]
+		},
+		{
+			"level": 4,
+			"name": "Critical Compiler Errors (Code must follow Clean Code and best practices)",
+			"rules": ["complexity", "max-params", "max-depth"]
+		}
+	]
+}