@automaton-labs/aib 0.0.7 → 0.0.9

package/dist/help/dsl/help-index.md

@@ -1,44 +1,49 @@
-Run as: aib help <topic...>
-
-Start here if this is your first AIB pass:
-  bootstrap
-
-Always after context compaction:
-  aib help help-protocol quick-map
-  aib config aliases
-
-Help conventions:
-  help-format
-
-Refresh workflow model:
-  basics patterns
-
-Core focused topics:
-  session
-  prefs
-  selectors
-  dsl
-  inspect
-  mutation
-
-Feature topics:
-  inspect.file
-  inspect.imports
-  inspect.exports
-  inspect.members
-  inspect.code
-  inspect.deps
-  inspect.usages
-  inspect.graph
-  inspect.tree
-  inspect.duplicates
-  inspect.cycles
-  rename
-  move
-  modulePlan
-  refactor.batch
-  imports.normalize
-  view
-  qr
-  rg
+Run as: aib help <topic...>
+
+Start here if this is your first AIB pass:
+  bootstrap
+
+Always after context compaction:
+  aib help help-protocol quick-map recipes rules
+  aib config aliases
+
+Help conventions:
+  help-format
+
+Refresh workflow model:
+  basics patterns
+
+Core focused topics:
+  session
+  rules
+  selectors
+  dsl
+  inspect.shared
+  mutation.shared
+  recipes
+
+Feature topics:
+  inspect.file
+  inspect.imports
+  inspect.exports
+  inspect.members
+  inspect.code
+  inspect.deps
+  inspect.usages
+  inspect.graph
+  inspect.tree
+  inspect.aliasCandidates
+  inspect.duplicates
+  inspect.cycles
+  rename
+  move
+  moveToDir
+  renameFile
+  mutate.mixed
+  modulePlan
+  import.rebase
+  imports.normalize
+  view
+  qr
+  rg
   reveal

package/dist/help/dsl/snippets/agents.md

@@ -10,5 +10,5 @@ Use {{docsPath}} when working with TS/JS code.
 Help fallback:
 For TS/JS code work, use aib. Start with {{docsPath}}. If local docs are not enough, run `aib help bootstrap`.
 
-Refactor-focused:
-When changing TS/JS code, use aib for semantic discovery, usages, graph, rename, move, and modulePlan. Start with {{docsPath}}.
+Refactor-focused:
+When changing TS/JS code, use aib for semantic discovery, usages, graph, and mutate DSL. Start with {{docsPath}}.

package/dist/help/dsl/tokens/qr.inline.examples.md

@@ -1,2 +1,2 @@
 Inline:
-aib qr @scripts/a.txt h=80 @scripts/b.py o=300 l=50 @logs/app.log all
+aib qr @svc/users.ts s=3:42,66:84,92 @scripts/a.txt h=80 @scripts/b.py r=300:50,500 .prettierrc all

package/dist/help/dsl/topics/basics.md

@@ -8,5 +8,5 @@ Prefer batch DSL instead of one-off inline calls.
 One request can inspect/mutate several files/entities and save reusable artifacts when supported.
 Use one-off commands only for small checks/changes.
 
-For mutations, aib asks TS/IDE refactors to update affected references and imports.
+For mutations, aib asks TypeScript semantic refactors to update affected references and imports.
 After a successful mutation, do not manually patch the same imports unless aib reports a follow-up or the build/checks show a real issue.

package/dist/help/dsl/topics/config-setup.import-normalize.md

@@ -1,18 +1,18 @@
-Configure import normalization intent.
-
-importNormalize defines default normalization rules for explicit aib imports normalize commands.
-Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
-
-It does not run automatically during move/modulePlan.
-Use importRules for mutation-time import cleanup.
-
-Set importNormalize when the intended cleanup has project meaning:
-- adopting a new tsconfig alias across a project area;
-- converting an area to aliases;
-- converting scripts/tools or extracted modules to relative imports;
-- excluding generated or bundled output from normalization.
-
-For tiny one-file checks, inline options are fine.
+Configure import normalization intent.
+
+importNormalize defines default normalization rules for explicit aib imports normalize commands.
+Use it before broad or important import cleanup so the scope, target style, preferred alias, and excludes are stored in aib.json instead of repeated in command arguments.
+
+It does not run automatically during move/modulePlan.
+Use importRules for mutation-time import cleanup.
+
+Set importNormalize when the intended cleanup has project meaning:
+- adopting a new tsconfig alias across a project area;
+- converting an area to aliases;
+- converting scripts/tools or extracted modules to relative imports;
+- excluding generated or bundled output from normalization.
+
+For tiny one-file checks, inline options are fine.
 Before wider cleanup, put the intended rule in config and preview the smallest useful scope.
 
 Fields:
@@ -29,56 +29,56 @@ shortestAlias  rewrite to the shortest valid alias specifier
 preferAlias:
 @shared/*      prefer one alias pattern when several aliases can resolve the same file
 
-Alias cleanup:
-
-"importNormalize": [
-  {
-    "scope": "src",
-    "to": "shortestAlias",
-    "preferAlias": "@/*",
-    "exclude": [
-      "src/generated",
-      "src/**/dist"
-    ]
-  }
+Alias cleanup:
+
+"importNormalize": [
+  {
+    "scope": "src",
+    "to": "shortestAlias",
+    "preferAlias": "@/*",
+    "exclude": [
+      "src/generated",
+      "src/**/dist"
+    ]
+  }
+]
+
+Relative cleanup for scripts/tools:
+
+"importNormalize": [
+  {
+    "scope": "scripts",
+    "to": "relative",
+    "exclude": [
+      "scripts/**/*.cjs",
+      "scripts/**/*.mjs"
+    ]
+  }
 ]
 
-Relative cleanup for scripts/tools:
-
-"importNormalize": [
-  {
-    "scope": "scripts",
-    "to": "relative",
-    "exclude": [
-      "scripts/**/*.cjs",
-      "scripts/**/*.mjs"
-    ]
-  }
-]
-
-If you have not just checked config rules, run:
-
-aib config rules
-
-After editing aib.json, run:
-
-aib sync
-
-Then preview the smallest useful scope before applying:
-
-aib imports normalize preview <scope>
-
-Preview shows counts, sample import rewrites, a planId, and the apply command.
-It does not change project files.
-
-If preview changes imports outside the intended area, narrow scope or add exclude.
-
-If preview does not use the expected alias, check tsconfig aliases:
-
-aib reveal tsaliases
-
-If the config and aliases look correct but preview still looks stale or strange, run:
-
-aib sync
-
+If you have not just checked config rules, run:
+
+aib config rules
+
+After editing aib.json, run:
+
+aib sync
+
+Then preview the smallest useful scope before applying:
+
+aib imports normalize preview <scope>
+
+Preview shows counts, sample import rewrites, a planId, and the apply command.
+It does not change project files.
+
+If preview changes imports outside the intended area, narrow scope or add exclude.
+
+If preview does not use the expected alias, check tsconfig aliases:
+
+aib reveal tsaliases
+
+If the config and aliases look correct but preview still looks stale or strange, run:
+
+aib sync
+
 Then preview again.

package/dist/help/dsl/topics/config-setup.import-rules.md

@@ -7,11 +7,12 @@ Check current config:
 
 aib config rules
 
-importRules control imports created or expanded by move/modulePlan mutation cleanup.
-They do not rewrite the whole project.
-
-AIB starts from IDE/TS import preferences.
-For mutation cleanup, matching importRules in aib.json take priority.
+importRules control imports created or expanded by move/modulePlan mutation cleanup.
+They do not rewrite the whole project.
+
+A non-empty importRules block in aib.json is the complete AIB import-style authority.
+Omitted fields keep TypeScript/AIB defaults; they are not filled from editor settings.
+When importRules is empty, AIB may reuse explicit workspace-local IDE/TS preferences.
 Do not assume IDE/TS defaults match the repo style.
 
 Fields:

package/dist/help/dsl/topics/first-setup.md

@@ -81,11 +81,12 @@ Example:
 
 5. Configure import rules
 
-importRules control imports created or expanded by move/modulePlan mutation cleanup.
-They do not rewrite the whole project.
-
-AIB starts from IDE/TS import preferences.
-For mutation cleanup, matching importRules in aib.json take priority.
+importRules control imports created or expanded by move/modulePlan mutation cleanup.
+They do not rewrite the whole project.
+
+A non-empty importRules block in aib.json is the complete AIB import-style authority.
+Omitted fields keep TypeScript/AIB defaults; they are not filled from editor settings.
+When importRules is empty, AIB may reuse explicit workspace-local IDE/TS preferences.
 Do not assume IDE/TS defaults match the repo style.
 
 Fields:

package/dist/help/dsl/topics/help-protocol.md

@@ -1,5 +1,5 @@
 After context compaction, always run:
-aib help help-protocol quick-map
+aib help help-protocol quick-map recipes rules
 aib config aliases
 
 Use focused help when you would otherwise guess how a known AIB capability works.
@@ -14,11 +14,12 @@ aib help config-setup.import-normalize imports.normalize
 
 Refresh focused config help by signal:
 - repeated long paths: aib help config-setup.aliases
-- wrong move/modulePlan imports: aib help config-setup.import-rules
+- imports created by mutation do not match repo style: aib help config-setup.import-rules
 - noisy tree/graph output: aib help config-setup.excludes
 - too many visible tsconfigs: aib help config-setup.tsconfigs
 
 When refreshing multiple areas, request them together instead of one by one.
+Include broad shared topics only once.
 
 Example:
-aib help patterns mutation inspect inspect.file inspect.code imports.normalize
+aib help mutation moveToDir renameFile inspect inspect.file inspect.deps

package/dist/help/dsl/topics/import.base.md

@@ -0,0 +1,36 @@
+Import mutations change import declarations and import/export specifiers.
+
+Use them when the import target or import style is the intent.
+
+Current import mutation intents:
+- imports.normalize changes import style for already-correct targets.
+- imports.useBarrel moves eligible consumers to a barrel/index boundary.
+- imports.useDirect moves eligible consumers from a barrel back to direct source imports.
+
+Do not use imports.normalize when the real intent is to force a specific barrel boundary.
+Do not use imports.useBarrel/useDirect when the real intent is only alias-vs-relative style cleanup.
+
+Shared controls:
+
+@scope       consumer file or directory scope to scan
+@files       explicit consumer files to scan
+pathExclude  files, directories, or glob-like patterns to skip
+symbols      exported names to update, when supported by the operation
+
+Prefer @scope for a bounded area.
+Use @files for a small known consumer set.
+Use pathExclude for tests, generated files, fixtures, or migration-excluded areas.
+
+Use symbols only when the request should affect part of the import surface.
+Do not add symbols by default.
+
+Choose the import operation by intent:
+
+Use imports.normalize after imports already point to the right files/modules, but their specifier style should change.
+
+Use imports.useBarrel when an existing barrel/index file should become the import boundary.
+
+Use imports.useDirect when a barrel boundary should be removed for selected consumers.
+
+If both target boundary and style are wrong, change the boundary first.
+Normalize style only after the boundary is correct.

package/dist/help/dsl/topics/import.rebase.md

@@ -0,0 +1,83 @@
+Import Boundary Mutations
+
+Import boundary mutations change where consumers import exported symbols from.
+
+Use imports.useBarrel when an existing barrel file should become the import boundary.
+Use imports.useDirect when consumers currently import through a barrel but should import directly from source files.
+
+Both operations scan a consumer scope and rewrite eligible ES named imports.
+
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
+
+If a name is ambiguous, use selectors.
+
+Syntax:
+
+@scope <consumer-scope>
+imports.useBarrel <barrel-file> [pathExclude=[...]] [symbols=[...]]
+
+@scope <consumer-scope>
+imports.useDirect <barrel-file> [pathExclude=[...]] [symbols=[...]]
+
+Controls:
+
+@scope       consumer file or directory scope to scan
+pathExclude  consumer files, directories, or glob-like patterns to leave unchanged
+symbols      exported barrel names to update
+
+Use pathExclude for tests, generated files, fixtures, or migration-excluded areas.
+
+By default, do not list symbols.
+AIB reads the barrel and rewrites eligible imports for exported names it can resolve.
+Use symbols only when the request must affect a specific subset of the barrel surface.
+
+Run:
+aib mutate execute --stdin
+
+Use a barrel as the import boundary:
+
+Input:
+@scope src/features
+imports.useBarrel src/logs/index.ts
+
+Use direct source imports instead of a barrel:
+
+Input:
+@scope src/features
+imports.useDirect src/logs/index.ts
+
+Skip consumers that should not be rewritten:
+
+Input:
+@scope src/features
+imports.useBarrel src/logs/index.ts pathExclude=["**/*.test.ts","src/generated/**"]
+
+Limit the request to selected exported names:
+
+Input:
+@scope src/features
+imports.useDirect src/logs/index.ts symbols=[parseLogsQuery,LogsQuery]
+
+Compatibility
+
+Supported:
+- ES named imports
+- named re-exports
+- star re-exports
+- type-only named imports
+- aliased named re-exports
+
+Skipped or unsupported:
+- CommonJS require/module.exports
+- default re-exports
+- namespace imports
+- side-effect imports
+- default import parts
+
+Skipped imports are not rewritten.

package/dist/help/dsl/topics/inspect.aliasCandidates.md

@@ -0,0 +1,37 @@
+Find repeated TypeScript import prefixes that may be worth turning into TS path aliases.
+
+Use aliasCandidates when imports share long prefixes and you want evidence for adopting an existing alias or creating a new one.
+
+The advisor collects lexical import evidence, then validates shortlisted candidates against repo topology and TypeScript resolution for every owning tsconfig. Incomplete coverage, incompatible mappings, package-boundary violations, and other hard conflicts are rejected rather than rescued by ranking.
+
+Output separates evidence filters from the provisional ranking policy. Token savings use a deterministic path estimate and are not a Codex billing estimate. Parent and child candidates are compared by marginal coverage so overlapping imports are not counted twice.
+
+Candidates are classified as recommended, review, optional, or rejected. Creating a new alias remains review-only when runtime support or token confidence is not proven.
+
+This command is a read-only advisor. It does not edit tsconfig or rewrite imports.
+
+Run:
+aib inspect aliasCandidates <scope>
+
+DSL:
+aliasCandidates scope=src/main limit=20
+
+Options:
+limit       max candidates to print
+minImports  lexical evidence prefilter; not the ranking threshold
+minFiles    importing-file evidence prefilter; not the ranking threshold
+candidate   filter by source prefix or alias pattern
+detail      sum or examples
+
+Find candidates:
+
+Run:
+aib inspect aliasCandidates src/main
+
+Show examples for one suggested alias:
+
+Run:
+aib inspect aliasCandidates src/main --candidate "#services/*" --detail examples
+
+DSL:
+aliasCandidates scope=src/main candidate="#services/*" detail=examples

package/dist/help/dsl/topics/inspect.code.md

@@ -1,10 +1,4 @@
-Use code to fetch exact declarations or members.
-It returns focused code without reading the whole file.
-
-Good for:
-- reading a known function, class, method, declaration, `default`, or `IIFE#N`
-- fetching several related code blocks in one request
-- keeping context focused on code needed for the current task
+Use code when you know file path and declaration/member selector, but do not know ranges.
 
 Controls:
 file, entity, entities, parent, show, ranges

package/dist/help/dsl/topics/inspect.file.md

@@ -2,30 +2,21 @@ Use file to map top-level declarations physically present in one file.
 Exported declarations are marked in the output.
 It shows what lives in the file before you decide whether to read code.
 
-Good for:
-- mapping a file
-- listing top-level declarations
-- seeing default exports, decorators, IIFEs, and runtime calls
+Good for:
+- mapping a file
+- listing top-level declarations
+- seeing default exports, decorators, IIFEs, and runtime calls
 - checking whether a file contains real declarations or mostly re-exports
 
-Do not add limit just in case.
-file output is compact and most files have far fewer than 100 top-level declarations.
-Use limit only after file output is actually too large.
-
-Controls:
-file, ranges, localOnly
-
-Specific:
-localOnly   show local declarations and reexports without resolving facade API; +localOnly
-
-Defaults: +ranges
+Controls:
+file, ranges
+
+Defaults: +ranges
 Use -ranges to show names without ranges.
 
 Run:
 aib inspect --stdin
 
-Input:
-file @svc/service.ts +localOnly
+Input:
+file @svc/service.ts
 file src/index.ts
-
-inspect file src/service.ts [--ranges] [--local-only]

package/dist/help/dsl/topics/inspect.graph.md

@@ -64,11 +64,10 @@ Use DSL or request flags to hide sections such as edges/hubs/entrypoints/leaves.
 
 Specialized graph command:
 Run:
-aib inspect graph --stdin
+aib inspect graph @svc --view local --save services-graph
 
-Input:
-graph scope=@svc view=local >services-graph
-graph from=aib:graph:services-graph focus=[@svc/users.ts,@svc/admins.ts] +symbolUsage -edges
+Focus saved graph:
+aib inspect graph --from-file aib:graph:services-graph --focus @svc/users.ts --focus @svc/admins.ts --symbol-usage
 
 Multiple scopes:
 Run:
@@ -86,19 +85,6 @@ aib inspect --stdin
 Input:
 graph scope=src view=local exclude=["**/*.test.ts","**/* copy.ts"] >src-graph
 
-Graph prefs:
-inspect.graph.edges boolean
-inspect.graph.hubs boolean
-inspect.graph.entrypoints boolean
-inspect.graph.leaves boolean
-inspect.graph.symbols boolean
-inspect.graph.symbolUsage boolean
-
-symbolUsage is usually the better first choice when imported names matter.
-
-Example:
-session prefs set inspect.graph.edges false inspect.graph.hubs false inspect.graph.symbolUsage true
-
 Output fields:
 summary       file/edge/package counts
 paths         compact path aliases used in text output

package/dist/help/dsl/topics/{inspect.md → inspect.shared.md}

@@ -9,18 +9,19 @@ map: learn what exists and how it connects
 focus: choose files/entities/usages that matter
 code: fetch exact code needed
 
-Choose inspect operation:
-
-declarations in one file         file
-static/dynamic imports           imports
-public API                       exports
-methods/properties of parent     members
-exact implementation             code
-outgoing deps of one entity      deps
-incoming references/callers      usages
-file/module connectivity         graph
-compact directory layout         tree
-repeated declarations/helpers    duplicates
+Choose inspect operation:
+
+declarations in one file         file
+static/dynamic imports           imports
+public API                       exports
+methods/properties of parent     members
+exact implementation             code
+outgoing deps of one entity      deps
+incoming references/callers      usages
+file/module connectivity         graph
+compact directory layout         tree
+path alias candidates            aliasCandidates
+repeated declarations/helpers    duplicates
 local import cycles              cycles
 
 Prefer one batch DSL request for related questions.

package/dist/help/dsl/topics/modulePlan.md

@@ -1,41 +1,36 @@
-Modes: preview/apply or execute.
-Use execute for routine changes.
-Use preview/apply when learning a mutation command or inspecting a large multi-step request before writing files.
+Run mutation DSL through aib mutate.
+Use execute for routine changes.
+Use preview/apply when you want to review intent before writing.
+
+Common commands:
+aib mutate preview --stdin
+aib mutate execute --stdin
+aib mutate apply <mutateId>
 
 If a name is ambiguous, use selectors.
 Run help selectors to refresh selector syntax.
 
-modulePlan is for splitting large files into smaller modules.
-Use it when a large file should be refactored into several target files.
-
-modulePlan orchestrates semantic moves and updates affected references/imports.
-
-If imports created by modulePlan do not match the repo style, run:
-aib help config-setup.import-rules
+Use module only for a full-file split: moving all declarations from one source file into target modules.
+Do not mix module with other mutation operations.
 
 Use +expectEmpty when your modulePlan intent is to move all declarations out of the source file.
 It does not change the move behavior; it only asks output to report remaining source declarations if any remain.
 Use it only when remaining declarations would mean the split did not match your intent.
 Do not use it for partial extractions.
 
-Plan:
-modulePlan preview --stdin
-modulePlan execute --stdin
-modulePlan apply <planId>
-
-Use preview/apply when you want to inspect the plan before writing files.
-Use execute when you want to preview and apply immediately.
+Focused syntax:
+module <targetFile>: <entity...>
+
+Split one large source file into several targets:
+Run:
+aib mutate execute --stdin
 
-Split one large source file into several targets:
-Run:
-aib modulePlan execute --stdin
-
 Input:
 @source src/large-service.ts +expectEmpty
 module src/large-service.types.ts: ServiceOptions ServiceMode
-module src/large-service.core.ts: LargeService createLargeService
-
-How inheritance works above:
-@source sets the source file once.
-+expectEmpty says no declarations should remain in the source after the plan.
+module src/large-service.core.ts: LargeService createLargeService
+
+How inheritance works above:
+@source sets the source file once.
++expectEmpty says no declarations should remain in the source after the plan.
 Each module line declares one target and the entities that should move there.