icore 1.0.4 → 1.0.5

package/docs/policy/decision-rule-policy.md

@@ -1,41 +0,0 @@
-# Decision Rule
-
-> Type: Policy. This document defines the baseline filter before any code change.
-
-If the change is not required, do not make it.
-
-If the change adds behavior, do not make it.
-
-If the change removes behavior, do not make it.
-
-If the change is made because "this is how it is usually done", do not make it.
-
-If the change seems safe, do not make it.
-
-If the change seems correct, do not make it.
-
-If there is doubt, leave the code as it is.
-
-Existing code is considered intentional.
-
-## Practical Application
-
-Before making a change, check the following in order:
-
-1. Is the change directly required by the task?
-2. Does it change behavior, pipeline, or project structure?
-3. Can the task be solved with a smaller change?
-4. Is the decision based on a heuristic instead of a requirement?
-
-## Examples
-
-Correct decision:
-
-- fix a specific conditional branch when the task is about an incorrect calculation
-- add a test for already required behavior
-
-Incorrect decision:
-
-- rewrite a module "while we are touching it"
-- add artifact cleanup because it feels customary
-- change the dependency graph for a subjective sense of order

package/docs/policy/dependencies-policy.md

@@ -1,49 +0,0 @@
-# Dependencies Policy
-
-> Type: Policy. This document defines criteria for choosing new libraries and signs of undesirable dependencies.
-
-Only high-quality libraries are allowed.
-
-A library must:
-
-- solve a broad problem
-- have a clear API
-- be maintained
-- provide architectural value
-- be justified long term
-
-Undesirable dependencies:
-
-- a package for one function
-- a package for deleting files
-- a package for a small utility
-- a package wrapper over a standard function
-
-Bad example:
-
-rimraf
-
-Good example:
-
-a general-purpose filesystem library
-with a complete API
-
-## Selection Examples
-
-Allowed:
-
-- add a library that covers a stable infrastructure task and is already needed in several places
-- choose a dependency with a clear support model and understandable documentation
-- prefer the standard library if it covers the task without architectural losses
-
-Not allowed:
-
-- add a package only for one call that would take a few lines of project code
-- pull in a dependency for "prettier" syntax
-- add a library if it duplicates a tool already used in the project
-
-## Good Practices
-
-- before adding a dependency, state which long-term task it solves
-- check whether the task can be covered by existing project libraries
-- evaluate not only API convenience but also the maintenance cost of the dependency

package/docs/policy/documentation-policy.md

@@ -1,27 +0,0 @@
-# Documentation Policy
-
-> Type: Policy. This document defines rules for choosing the documentation source of truth and forbids duplicating code contracts in permanent reference pages.
-
-## Purpose
-
-Documentation must help find the current contract, not create a second source of truth next to the code.
-
-If a contract is already expressed by a runtime mechanism, source file, config file, or tests, a Markdown document must link to that source and explain the working route instead of copying the full reference.
-
-## README And Docs
-
-README must remain a concise entry point to the project:
-
-- installation;
-- quick start;
-- main links;
-- important workflows.
-
-Detailed rules and policies must live in `docs/`.
-
-Navigation documents must help find the source of truth, not become a second README.
-
-## Minimum Rule
-
-Markdown must answer the question "where is the current contract and how should it
-be used". The contract itself must live where it is verified by runtime or tests.

package/docs/policy/index.md

@@ -1,49 +0,0 @@
-# Project Policies
-
-> Type: Navigation. This document provides navigation for the policy section and defines the general purpose of the project change constraints.
-
-This section contains project rules for changing Node.js/TypeScript codebases.
-
-The policy set is intended to preserve:
-
-- predictable project behavior;
-- reproducible builds;
-- public contract stability;
-- absence of accidental changes;
-- controlled code evolution.
-
-These policies are mandatory for developers, reviewers, and agents making changes in the repository.
-
-## Start Here
-
-- [Decision Rule](./decision-rule-policy.md) - the meta-policy for choosing between acceptable options.
-- [Change Policy](./change-policy.md) - the rule for the minimum sufficient change.
-
-## When To Read This Section
-
-- before starting code changes;
-- during code review;
-- when there is doubt whether a change is acceptable;
-- when a change affects scripts, documentation, dependencies, or architecture;
-- when public API, CLI behavior, build pipeline, or publish output changes.
-
-## Full List
-
-- [Decision Rule](./decision-rule-policy.md)
-- [Change Policy](./change-policy.md)
-- [Non-Functional Requirements](./non-functional-requirements.md)
-- [Abstraction Policy](./abstraction-policy.md)
-- [Naming Policy](./naming-policy.md)
-- [Comment Policy](./comment-policy.md)
-- [Testing Policy](./testing-policy.md)
-- [Scripts and Build Policy](./scripts-and-build-policy.md)
-- [Dependencies Policy](./dependencies-policy.md)
-- [Documentation Policy](./documentation-policy.md)
-
-## Short Route
-
-When a change decision must be made quickly, it is enough to go through three documents:
-
-1. [Decision Rule](./decision-rule-policy.md)
-2. [Change Policy](./change-policy.md)
-3. [Non-Functional Requirements](./non-functional-requirements.md)

package/docs/policy/naming-policy.md

@@ -1,18 +0,0 @@
-# Naming Policy
-
-> Type: Policy. This document defines naming rules for code entities.
-
-## Goal
-
-Names in code must be consistent, predictable, and must not create false semantic signals.
-
-Name notation must reflect the entity role, not the author's personal preference.
-
-## Basic Naming Rules
-
-TypeScript/JavaScript code uses the following rules:
-
-- `camelCase` - variables, functions, values, exported const values;
-- `PascalCase` - classes, types, interfaces, enums;
-- `kebab-case` - runtime names and file names;
-- `SCREAMING_SNAKE_CASE` / `ALL_CAPS` - forbidden for internal project identifiers.

package/docs/policy/non-functional-requirements.md

@@ -1,31 +0,0 @@
-# Non-Functional Requirements
-
-> Type: Policy. This document defines the non-functional properties of the project that a working change must not violate.
-
-Changes must not break:
-
-- build reproducibility
-- determinism
-- portability
-- CI
-- runtime behavior
-- file structure
-- startup order
-- architecture
-- dependencies
-
-Even if the code works,
-a change is forbidden if it violates these properties.
-
-## Risk Examples
-
-- the build passes locally but depends on file ordering in a specific OS
-- the code works but changes the location of output artifacts
-- the change does not break logic but adds a dependency on shell-specific behavior
-- tests pass but the component startup order becomes different
-
-## Good Practices
-
-- verify not only result correctness but also preservation of previous side effects
-- avoid changes that bind the project to a specific execution environment
-- separately evaluate the impact of a change on CI, file structure, and reproducibility

package/docs/policy/scripts-and-build-policy.md

@@ -1,60 +0,0 @@
-# Scripts And Build Policy
-
-> Type: Policy. This document defines restrictions on changing scripts, build, and test pipeline.
-
-## Purpose
-
-Build, test, and run scripts are considered part of the runtime pipeline.
-
-They must not be changed without clear necessity.
-
-## Forbidden Changes
-
-Forbidden without a direct requirement:
-
-- add file deletion;
-- add automatic build output cleanup;
-- add a `clean` script for automatic cleanup before `build` or `test`;
-- add shell-specific cleanup commands;
-- add prebuild/postbuild hooks;
-- add pretest/posttest hooks;
-- change command order;
-- add chained commands for convenience;
-- replace portable runtime logic with shell commands.
-
-Example of a correct minimal script:
-
-```json
-"build": "<project-build-command>"
-```
-
-Example of an incorrect change:
-
-```json
-"build": "rm -rf <build-output> && <project-build-command>"
-```
-
-If stale artifacts remain in build output after files are moved, they must be removed narrowly and explicitly as part of that specific operation, not by changing the project's permanent build/test pipeline.
-
-File deletion is allowed only when the task explicitly requests it.
-
-## Additional Examples
-
-Allowed:
-
-- leave the existing `build` unchanged and fix the cause of the error in code;
-- add a new script only when the task directly requires a new entrypoint;
-- change the implementation of the invoked file without changing the run scenario itself, if the task is about that file's behavior.
-
-Not allowed:
-
-- change the test script so that it runs additional unrelated checks;
-- replace the existing build tool with another one without a direct task requirement;
-- add cleanup of temporary directories "just in case";
-- add automatic build output cleanup before `build` or `test`.
-
-## Good Practices
-
-- treat scripts as part of the project contract, not as an implementation detail;
-- if the problem can be solved inside the code, do not move the solution into shell commands;
-- before changing a script, check whether step order, side effects, and entrypoints change.

package/docs/policy/testing-policy.md

@@ -1,335 +0,0 @@
-# Testing Policy
-
-> Type: Policy. This document limits the addition of tests and test infrastructure.
-
-## Purpose
-
-Tests must protect production contracts, observable behavior, and boundary scenarios.
-
-A test must not lock in accidental implementation, temporary code structure, or internal action order unless this is part of the public contract.
-
-The main question a test must answer is:
-
-> Which behavior or production risk is protected?
-
-Not:
-
-> Which lines of code were executed?
-
-## How To Run Tests
-
-Tests are written in TypeScript in `src/**/*.test.ts` or `src/**/*.spec.ts` and use standard Node.js modules:
-
-- `node:test`;
-- `node:assert`.
-
-Before running tests after changes in `src`, rebuild the project:
-
-```bash
-npm run build
-npm test
-```
-
-## Test Requirements
-
-Tests must be:
-
-- isolated;
-- deterministic;
-- readable;
-- minimal but sufficient;
-- focused on one behavior;
-- oriented toward observable result, not internal implementation.
-
-One test must verify one behavior.
-
-Multiple assertions in one test are allowed if they describe the same contract. If assertions verify different reasons for behavior changes, they must be split into separate tests.
-
-## Test File Boundary
-
-A test file must cover a specific production file, not a directory.
-
-Mapping rule:
-
-```text
-src/bootstrap/help/renderer.ts      -> src/bootstrap/help/renderer.test.ts
-src/bootstrap/help/commands.ts      -> src/bootstrap/help/commands.test.ts
-src/bootstrap/help/help.ts          -> src/bootstrap/help/help.test.ts
-src/bootstrap/cli.ts                -> src/bootstrap/cli.test.ts
-src/bootstrap/config.ts             -> src/bootstrap/config.spec.ts
-```
-
-Creating a test whose name looks like a test for a directory or barrel module is forbidden:
-
-```text
-src/bootstrap/help.test.ts          # covers the help/ directory
-src/bootstrap/help.spec.ts          # covers the help/ directory
-src/bootstrap/help/index.test.ts    # covers a barrel-only index.ts
-```
-
-An exception is allowed only if the file is actually a runtime entrypoint
-or a package entrypoint with its own behavior. In that case, the test must
-verify the entrypoint behavior itself, not the internal files of the directory.
-
-If `index.ts` contains only re-exports, a separate test for it is not needed.
-Files that contain logic must be tested.
-
-## Imports In Tests
-
-Unit tests must import code from the specific file they verify.
-
-Allowed:
-
-```ts
-import { renderCliHelp } from './renderer';
-import { isHelpRequested } from './help'; // if there is a nearby help.ts file
-```
-
-Forbidden for a unit test of a specific file:
-
-```ts
-import { renderCliHelp } from './index';
-import { renderCliHelp } from '../help';
-```
-
-The second example is forbidden if `../help` resolves to a directory or barrel,
-not to a specific file.
-
-An integration test may go through a public entrypoint if it verifies
-observable entrypoint behavior: exit code, stdout/stderr, dispatch, wiring, or
-public API contract.
-
-## Isolation
-
-A test must minimize dependence on:
-
-- the real filesystem, unless filesystem behavior is being tested;
-- network;
-- current time;
-- test execution order;
-- external processes;
-- global mutable state;
-- stale build artifacts.
-
-If dependence on an external resource is the essence of the test, it must be clearly visible from the test name, suite, or fixture.
-
-## Test Data
-
-Test data must be minimal but sufficient for the scenario.
-
-There is no need to create a realistic dataset if one object with three fields is enough for the check.
-
-Good:
-
-```ts
-test('returns undefined for an unknown path', () => {
-  const throttle = new Throttle({
-    KnownService: 100
-  });
-
-  assert.equal(
-    throttle.resolveLimit('/api.contract.v1.UnknownService/Get'),
-    undefined
-  );
-});
-```
-
-Bad:
-
-```ts
-test('validates throttling', () => {
-  const throttle = new Throttle({
-    ExamplesService: 200,
-    DataService: 300,
-    OperationsService: 200,
-    SandboxService: 200,
-    UsersService: 100
-  });
-
-  assert.equal(
-    throttle.resolveLimit('/api.contract.v1.UnknownService/Get'),
-    undefined
-  );
-});
-```
-
-Extra fields hide the reason for the test and increase maintenance cost.
-
-## Test Suite Naming
-
-Test names must describe the public API path and expected behavior.
-
-Top-level `describe()` names the unit under test:
-
-- `ClassName` for classes and runtime components;
-- `functionName` for standalone exported functions;
-- `objectName` for exported objects or namespaces;
-- `module-name` only when several closely related exports are tested and there is no single primary subject.
-
-Good:
-
-```ts
-describe('Throttle', () => {
-  // ...
-});
-
-describe('createSdkMetadata', () => {
-  // ...
-});
-
-describe('suite runner helpers', () => {
-  // ...
-});
-```
-
-Bad:
-
-```ts
-describe('utils', () => {
-  // ...
-});
-
-describe('tests for sdk', () => {
-  // ...
-});
-```
-
-## Nested Suite Naming
-
-Nested `describe()` names a public member or operation:
-
-- `constructor` for constructor behavior;
-- `#methodName` for instance methods called as `instance.methodName()`;
-- `.methodName` for static methods called as `ClassName.methodName()`;
-- `.methodName` for exported object/namespace methods called as `objectName.methodName()`;
-- `functionName` for standalone functions grouped under a module-level suite.
-
-Examples:
-
-```ts
-describe('Throttle', () => {
-  describe('#resolveLimit', () => {
-    // ...
-  });
-
-  describe('#reduce', () => {
-    // ...
-  });
-});
-
-describe('suite runner helpers', () => {
-  describe('collectTestFiles', () => {
-    // ...
-  });
-});
-```
-
-A parent suite must not contain sibling `describe()` blocks with the same name. If two blocks have the same name, they must be merged or named after different public scenarios.
-
-## Test Case Naming
-
-`test()` names only expected behavior.
-
-The test name must not repeat the subject or method name if they are already stated in `describe()`.
-
-Good:
-
-```ts
-describe('Throttle', () => {
-  describe('#resolveLimit', () => {
-    test('returns undefined for an unknown path', () => {
-      // ...
-    });
-  });
-});
-```
-
-Bad:
-
-```ts
-describe('Throttle', () => {
-  describe('#resolveLimit', () => {
-    test('Throttle resolveLimit returns undefined for an unknown path', () => {
-      // ...
-    });
-  });
-});
-```
-
-Repeating the subject makes the name noisy and worsens test output readability.
-
-## Preferred Behavior Verbs
-
-Preferred verbs for `test()`:
-
-- `returns ...`;
-- `throws ...`;
-- `rejects ...`;
-- `parses ...`;
-- `formats ...`;
-- `writes ...`;
-- `reads ...`;
-- `keeps ...`;
-- `skips ...`;
-- `uses ...`;
-- `does not ...`;
-- `handles ...`;
-- `preserves ...`;
-- `computes ...`;
-- `maps ...`;
-- `normalizes ...`;
-- `ignores ...`.
-
-Good:
-
-```ts
-test('throws for unknown unary limit path', async () => {
-  // ...
-});
-
-test('does not throttle response streams', async () => {
-  // ...
-});
-```
-
-Bad:
-
-```ts
-test('works correctly', () => {
-  // ...
-});
-
-test('should process data', () => {
-  // ...
-});
-```
-
-`should` is not technically forbidden, but the preferred style is a direct description of observable behavior without an extra modal word.
-
-## Explicitness Over DRY
-
-The drive toward DRY does not apply to tests.
-
-Repetition in tests is allowed if it:
-
-* keeps the scenario local;
-* removes non-obvious setup;
-* reduces the risk of mistakes in test infrastructure;
-* allows the test case to be read without jumping to helpers.
-
-A bad test is worse than no test: it creates false confidence and makes code harder to change.
-
-## Generalization In Tests
-
-Helpers in tests are almost always undesirable.
-
-A helper is allowed only if it removes technical noise and does not hide the meaning of the scenario.
-If a helper is more complex than the test itself, it must be removed.
-If a large helper, fixture builder, or conditional test logic is needed for a check, this may signal that production code is poorly separated or that the test is at the wrong level.
-A direct test with explicit data is preferable to abstract test infrastructure.
-
-## Coverage Boundaries
-
-There is no need to try to cover the entire public method or contract with one large test.
-If composite behavior sections are already checked separately, an additional large test appears unnecessary.
-It is allowed to leave some sections without direct coverage if they are already indirectly protected by other tests.