icore 1.0.3 → 1.0.4

package/docs/git-flow.md

@@ -0,0 +1,188 @@
+# Git Flow
+
+This project uses a classic Git Flow branching model.
+
+## Long-Lived Branches
+
+### `master`
+
+`master` is the production and package provenance branch.
+
+- Contains only released code.
+- Receives completed releases from `release/*` branches.
+- Receives urgent production fixes from `hotfix/*` branches.
+- Each release commit on `master` must have a semver tag, for example `v1.1.5`.
+
+Do not commit feature work directly to `master`.
+
+### `legacy/v1`
+
+`legacy/v1` preserves the historical `icore@0.1.38` codebase.
+
+- Points to the final legacy package state.
+- Must remain available for provenance and historical reference.
+- Must not receive new development work.
+- Must be pushed before any cleanup or replacement of legacy files.
+
+### `develop`
+
+`develop` is the integration branch for active development.
+
+- New feature branches start from `develop`.
+- Completed feature branches are merged back into `develop`.
+- Release branches start from `develop`.
+- Hotfix branches are merged back into `develop` after they are released from `master`.
+
+Do not release directly from `develop`.
+
+## Short-Lived Branches
+
+### `feature/*`
+
+Use `feature/*` branches for regular development work.
+
+Naming:
+
+```bash
+feature/<short-description>
+```
+
+Example:
+
+```bash
+feature/restore-public-api
+```
+
+Flow:
+
+```bash
+git switch develop
+git switch -c feature/restore-public-api
+
+# make changes, run checks
+git add .
+git commit -m "fix: restore public API"
+
+git switch develop
+git merge --no-ff feature/restore-public-api
+git branch -d feature/restore-public-api
+git push origin develop
+```
+
+### `release/*`
+
+Use `release/*` branches to prepare a version for release.
+
+Naming:
+
+```bash
+release/v<major>.<minor>.<patch>
+```
+
+Example:
+
+```bash
+release/v1.1.5
+```
+
+Allowed changes on a release branch:
+
+- Version bump.
+- Changelog or release notes.
+- Release-only documentation.
+- Small release blockers found during validation.
+
+Do not add unrelated feature work to a release branch.
+
+Flow:
+
+```bash
+git switch develop
+git switch -c release/v1.1.5
+
+# version/changelog/release fixes, run checks
+git add .
+git commit -m "chore: prepare release v1.1.5"
+
+git switch master
+git merge --no-ff release/v1.1.5
+git tag -a v1.1.5 -m "Release v1.1.5"
+
+git switch develop
+git merge --no-ff release/v1.1.5
+
+git branch -d release/v1.1.5
+git push origin master develop --tags
+```
+
+### `hotfix/*`
+
+Use `hotfix/*` branches only for urgent fixes to released code.
+
+Naming:
+
+```bash
+hotfix/v<major>.<minor>.<patch>
+```
+
+Example:
+
+```bash
+hotfix/v1.1.6
+```
+
+Flow:
+
+```bash
+git switch master
+git switch -c hotfix/v1.1.6
+
+# make fix, run checks
+git add .
+git commit -m "fix: correct production issue"
+
+git switch master
+git merge --no-ff hotfix/v1.1.6
+git tag -a v1.1.6 -m "Release v1.1.6"
+
+git switch develop
+git merge --no-ff hotfix/v1.1.6
+
+git branch -d hotfix/v1.1.6
+git push origin master develop --tags
+```
+
+## Tags
+
+Every released version must be tagged from `master`.
+
+Use annotated tags:
+
+```bash
+git tag -a v1.1.5 -m "Release v1.1.5"
+git push origin --tags
+```
+
+Do not move release tags after they have been pushed.
+
+## Merge Policy
+
+Use merge commits for branch completion:
+
+```bash
+git merge --no-ff <branch>
+```
+
+This preserves the historical branch structure and matches the existing repository history.
+
+## Current Historical Baseline
+
+The repository preserves the old npm package history before new development:
+
+- `master` points to the final legacy release commit `3048f15`.
+- `legacy/v1` points to the same final legacy release commit `3048f15`.
+- npm `icore@0.1.38` was published from commit `3048f15`.
+- New alpha development starts from `develop`, not from `master`.
+
+Do not delete or rewrite `legacy/v1`. If a future `main` branch is introduced,
+decide that as a separate repository migration and keep `legacy/v1` intact.

package/docs/policy/abstraction-policy.md

@@ -0,0 +1,198 @@
+# Abstraction Policy
+
+> Type: Policy. This document defines rules for introducing interfaces, factories, registries, helpers, adapters, and shared modules.
+
+## Purpose
+
+This policy protects the project from premature generalization.
+
+A typical agent mistake is to create an interface, factory, registry, helper, or adapter before real repetition or an architectural boundary appears in the code.
+
+## Basic Rule
+
+An abstraction appears after repetition or an explicit boundary.
+
+Allowed reasons:
+
+- the logic is actually repeated;
+- there are two or more implementations;
+- there is an explicit boundary between business logic and infrastructure;
+- the code must be tested separately;
+- the inline solution has become more complex than a named abstraction;
+- the new abstraction reduces coupling between existing parts.
+
+Not allowed reasons:
+
+- "this is architecturally prettier";
+- "it may be useful later";
+- "other projects do it this way";
+- "a second implementation will appear someday";
+- "I want to hide the details";
+- "the file became visually long".
+
+## One Implementation
+
+One implementation usually does not require an interface.
+
+An interface is allowed with one implementation only if:
+
+- it is a public contract;
+- it is a boundary for an infrastructure adapter;
+- it is a test seam without which behavior cannot be checked reliably;
+- it is an external API requirement;
+- there is an owner decision for an extension point.
+
+Creating an interface only so that a class "depends on an abstraction" is forbidden.
+
+## Helpers
+
+A helper is introduced only if it reduces complexity.
+
+Allowed:
+
+- extract a repeated non-trivial calculation;
+- name a complex condition when the name exposes business meaning;
+- hide an integration detail inside an infrastructure boundary;
+- remove duplication that has already appeared in the current task.
+
+Not allowed:
+
+- wrap one standard function without a new responsibility;
+- hide an important branch behind a too-generic name;
+- create `utils` for one line;
+- extract two similar lines when the similarity is accidental;
+- create a helper that forces readers to open more files to understand simple behavior.
+
+A good helper makes the calling code clearer. A bad helper hides meaning and increases navigation.
+
+## Factories
+
+A factory is needed when object creation itself has become a separate responsibility.
+
+Allowed:
+
+- creation logic contains branching;
+- several dependencies must be assembled;
+- there is lifecycle or resource ownership;
+- there are several supported creation modes;
+- the factory is public API.
+
+Not allowed:
+
+- create `createX()` only instead of `new X()`;
+- extract a constructor call for consistency;
+- create a factory before lifecycle/branching/dependency assembly appears.
+
+## Registries
+
+A registry is needed only for dynamic selection from a set of known implementations.
+
+Allowed:
+
+- there are several registered handlers/adapters;
+- selection happens by runtime key;
+- the set of entries is part of the contract;
+- duplicate switch/lookup logic has already appeared.
+
+Not allowed:
+
+- a registry with one item;
+- a registry "for the future";
+- a registry instead of a simple import;
+- a registry that hides the dependency graph.
+
+## Adapters
+
+An adapter is needed at a boundary with an external system, library, filesystem, network, framework, or process API.
+
+Allowed:
+
+- separate an external type from an internal/public contract;
+- isolate library-specific behavior;
+- normalize external errors;
+- hide environment-specific IO.
+
+Not allowed:
+
+- create an adapter for an internal function without an external boundary;
+- introduce an adapter only for naming symmetry;
+- leak an adapter type into public API without an owner decision.
+
+## Shared / Common / Utils
+
+A shared module is allowed only when it has a clear responsibility.
+
+Forbidden:
+
+- create `utils`, `common`, `shared`, or `helpers` as a dumping ground;
+- move code there without naming the responsibility;
+- mix unrelated helpers;
+- use a shared module as a bypass around an architectural boundary.
+
+If shared code is needed, the name must describe the role:
+
+```text
+config/
+filesystem/
+diagnostics/
+formatting/
+runtime/
+```
+
+If the role cannot be named more precisely, the abstraction is not ready yet.
+
+## Local Simplicity
+
+Local simplicity is more important than "beautiful architecture".
+
+Preferred:
+
+- keep a simple condition inline;
+- keep one implementation without an interface;
+- keep a direct call without a factory;
+- keep an explicit import without a registry;
+- keep local code next to its only usage.
+
+Architectural form is justified only when it reduces current complexity, not when it demonstrates future design.
+
+## Frequency Rule
+
+Practical rule:
+
+```text
+1 use  -> inline
+2 uses -> consider whether this is the same responsibility
+3+ uses -> consider an abstraction
+```
+
+The number of repetitions is not enough by itself. The repetition must have the same reason to change.
+
+## Check Before Extracting
+
+Before adding an abstraction, answer:
+
+1. What current problem is being solved?
+2. Is there repetition or an explicit boundary?
+3. Will the code be easier to read at the call site?
+4. Is important behavior being hidden?
+5. Is a public/internal contract being created for the future?
+6. Can the task be solved locally in a simpler way?
+
+If the answers are unconvincing, the abstraction is not added.
+
+## Examples
+
+Allowed:
+
+- extract repeated config parsing when it is used in several modules with the same reason to change;
+- create an adapter for filesystem access when business logic must not know about IO;
+- create a factory when runtime object creation requires lifecycle and several dependencies;
+- create a registry when there are several handlers and runtime dispatch.
+
+Not allowed:
+
+- create `utils.ts` for one function;
+- create an interface for a single class without a boundary;
+- create a registry with one handler;
+- create a factory that only calls a constructor;
+- extract a helper so that the calling code loses important context.

package/docs/policy/change-policy.md

@@ -0,0 +1,86 @@
+# Change Policy
+
+> Type: Policy. This document defines the minimum acceptable change rule.
+
+## Minimality Of Changes
+
+A change must be the minimum necessary change required to solve the task.
+
+Forbidden:
+
+- large refactoring without a request
+- cleanup without justification
+- style changes outside the affected area
+- architecture changes
+- pipeline changes
+- scripts changes
+- behavior changes
+
+Existing code is considered intentional.
+
+If a change is not required, it must not be made.
+
+## Local Improvements
+
+Small improvements are allowed when they are directly related to the current task.
+
+Allowed:
+
+- remove local duplication
+- improve naming
+- simplify readability
+- fix a nearby obvious defect
+- improve local tests
+
+Conditions:
+
+- behavior does not change
+- the change remains local
+- the improvement helps solve the current task
+
+If an improvement is outside the task scope, it should be proposed separately.
+
+## Examples
+
+Allowed:
+
+- fix a specific defect in one module without rewriting neighboring code
+- add a focused test for a new requirement without changing the existing test pipeline
+- extend an existing `if` branch when this is directly required by the task
+
+Not allowed:
+
+- mass-rename entities for consistency
+- perform unrelated renames in other modules
+- rewrite an entire module instead of fixing one branch
+- change file structure only because it seems more convenient
+
+## Module Boundaries
+
+Bad structure should not be preserved only because it already exists.
+
+Allowed:
+
+- fix poor local naming
+- clarify a module responsibility
+- move a small amount of code to improve readability
+
+Not allowed:
+
+- redesign a subsystem
+- move files in bulk
+- change architectural boundaries without a request
+
+## Good Practices
+
+- before making a change, state which exact task requirement the change covers
+- limit the diff to files that actually participate in the task
+- check whether the change affects behavior outside the required scenario
+
+## Environment Issues
+
+Environment issues are not a reason to change project code.
+
+If validation cannot run because of missing tools, permissions, cache, shell utilities, or container limitations, stop, describe the problem, and ask for a decision.
+
+Using a local temporary cache/workdir is allowed only if it does not change the project and does not expand the task scope.

package/docs/policy/comment-policy.md

@@ -0,0 +1,253 @@
+# Comment Policy
+
+> Type: Policy. This document defines rules for writing comments in production code.
+
+## Purpose
+
+Comments must explain a module role, responsibility boundaries, invariants, and reasons for non-obvious decisions.
+
+A comment must not duplicate code, retell obvious mechanics, or replace clear names for functions, types, and variables.
+
+The main question a comment must answer is:
+
+> Why does this decision exist in this form?
+
+Not:
+
+> What does this line do?
+
+## Basic Rules
+
+1. In each production module that participates in runtime, defines a layer contract, or contains non-trivial responsibility, one top architectural block is allowed.
+2. The top architectural block must describe the file role, allowed responsibility, module boundaries, and foreign responsibility that must not be moved into this file.
+3. Local comments are allowed only where the reason for a decision, invariant, or constraint would be lost without them.
+4. Obvious code actions do not need comments.
+5. JSDoc for public contracts must be short and specific.
+6. Within one file, comment style and language must be consistent.
+7. A comment must explain "why" or "for what purpose", not retell "what the line does".
+8. A comment must not expand the code contract. If a comment mentions a guarantee, invariant, execution order, safety, or constraint, it must be backed by code, types, or tests.
+9. Refactoring history must not be stored in comments. Git, ADRs, and design notes exist for that.
+
+## Top Architectural Block
+
+The top block describes the whole module, not individual functions.
+
+Template:
+
+```ts
+/**
+ * Module <role of the file in the system>.
+ *
+ * Allowed here:
+ * - <responsibility 1>;
+ * - <responsibility 2>;
+ * - <responsibility 3>;
+ *
+ * This file must not contain <foreign responsibility>.
+ */
+```
+
+Good example:
+
+```ts
+/**
+ * The runtime config resolver module transforms external input
+ * into normalized launch settings.
+ *
+ * Allowed here:
+ * - reading supported config sources;
+ * - validating required fields;
+ * - forming diagnostics for invalid config;
+ *
+ * This file must not contain CLI rendering or network calls.
+ */
+```
+
+Bad example:
+
+```ts
+/**
+ * Config file.
+ */
+```
+
+This comment does not explain the module role, boundaries, or allowed responsibility.
+
+## Exceptions
+
+A top architectural block is not required for:
+
+- barrel export files;
+- build output;
+- test fixtures;
+- trivial files with one obvious type or constant;
+- temporary local helper files that do not define a production contract.
+
+If a file participates in production runtime, defines a layer contract, or contains non-trivial responsibility, a top block is allowed and must be meaningful.
+
+## Public Contract JSDoc
+
+JSDoc for public functions, classes, and interfaces must describe only contract-level details:
+
+- input constraints;
+- side effects;
+- errors;
+- lifecycle;
+- important guarantees;
+- external API constraints.
+
+JSDoc is not needed if the meaning is fully clear from the name, types, and code.
+
+Bad:
+
+```ts
+/**
+ * Creates a client.
+ */
+createClient(options);
+```
+
+Better:
+
+```ts
+/**
+ * Creates a runtime client from already validated options.
+ *
+ * The function does not read environment and does not change global state.
+ */
+createClient(options);
+```
+
+But if this is already obvious from the interface and tests, it is better not to add the comment.
+
+## When A Comment Is Needed
+
+A comment is needed if it explains:
+
+- module role;
+- layer boundary;
+- non-obvious invariant;
+- workaround;
+- external API constraint;
+- reason for an unusual branch;
+- reason for cleanup logic;
+- preservation of compatibility with an old contract;
+- an intentionally empty branch when absence of action is part of the logic;
+- placeholder / TODO with an explanation of why implementation is absent for now;
+- reason why a dependency is allowed exactly here.
+
+Good:
+
+```ts
+// CLI config has priority over file config:
+// this is an observable command contract, not a merge order detail.
+const options = mergeConfig(fileConfig, cliConfig);
+```
+
+Good:
+
+```ts
+// The first request is not delayed:
+// the rate limit constrains the interval between subsequent calls.
+if (lastRequestTime === undefined) {
+  lastRequestTime = now;
+  return;
+}
+```
+
+## When A Comment Is Not Needed
+
+A comment is not needed if:
+
+- the meaning is already clear from the function name, type, and code;
+- the comment repeats the line literally;
+- the comment describes trivial mechanics;
+- the comment explains language syntax;
+- the comment becomes outdated faster than the code itself;
+- the comment stores change history instead of the current reason for the decision.
+
+Bad:
+
+```ts
+// Create options
+const options = resolveOptions(input);
+```
+
+Bad:
+
+```ts
+// Check if path exists
+if (fs.existsSync(file)) {
+  return file;
+}
+```
+
+## TODO And Placeholder
+
+A TODO is allowed only if it explains:
+
+- why implementation is deferred;
+- which constraint is currently in effect;
+- under which condition this place must be revisited.
+
+Good:
+
+```ts
+// TODO: streaming mode requires an owner decision on public API shape.
+// Revisit after supported options are approved.
+```
+
+Bad:
+
+```ts
+// TODO: fix later
+```
+
+If a module or branch is intentionally empty, this must be stated explicitly.
+
+## Workaround Comments
+
+A workaround must explain the external constraint, not just describe the workaround.
+
+Good:
+
+```ts
+// External API returns an empty string instead of a missing value:
+// normalize it here so the domain layer works only with undefined.
+const value = rawValue === '' ? undefined : rawValue;
+```
+
+Bad:
+
+```ts
+// Normalize value
+const value = rawValue === '' ? undefined : rawValue;
+```
+
+## Comments And Architectural Boundaries
+
+A comment is useful when it protects a layer boundary.
+
+Good:
+
+```ts
+/**
+ * CLI entrypoint only transforms argv into command input.
+ *
+ * This file must not contain domain behavior, persistence, or network orchestration.
+ */
+```
+
+This block helps avoid mixing bootstrap and runtime behavior.
+
+## Good Comment Criterion
+
+A good comment helps understand:
+
+- why the module exists;
+- where its boundaries are;
+- which invariant must not be violated;
+- which external constraint affected the code;
+- why an obviously strange decision is actually intentional.
+
+If a comment can be deleted without losing meaning, it should be deleted.