@ngockhoale/ukit 3.5.4 → 3.5.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -0
- package/manifests/engineConformance.yaml +0 -13
- package/manifests/platform.full.yaml +25 -0
- package/package.json +3 -9
- package/src/cli/commands/indexTools.js +1 -0
- package/src/cli/commands/memory.js +44 -4
- package/src/core/applyPlan.js +25 -72
- package/src/core/diffPlan.js +38 -9
- package/src/core/managedTemplateMerge.js +146 -0
- package/src/core/memory/memoryCheckRun.js +13 -1
- package/src/core/memory/memoryFlags.js +5 -6
- package/src/core/memory/memoryHit.js +31 -15
- package/src/core/memory/policy.js +5 -0
- package/src/core/memory/recallEngine.js +39 -3
- package/src/core/memory/recallLanes.js +182 -0
- package/src/core/memory/retrieval.js +13 -1
- package/src/core/memory/store.js +17 -0
- package/src/core/memory/topicCommand.js +75 -0
- package/src/core/memory/topicPages.js +545 -0
- package/src/core/metadata.js +12 -8
- package/src/core/runInstallPipeline.js +16 -10
- package/src/core/runtimeConfig.js +59 -83
- package/src/core/uninstall.js +8 -1
- package/src/decision/registry.js +33 -16
- package/src/decision/runtimeDecide.js +5 -5
- package/src/index/buildIndex.js +287 -6
- package/src/index/languageTools.js +100 -0
- package/src/index/paths.js +2 -1
- package/src/index/queryIndex.js +174 -10
- package/src/index/routeResolver.js +2 -2
- package/src/index/semanticLane.js +269 -0
- package/src/learning/lessonClass.js +110 -0
- package/src/learning/patternProposals.js +111 -7
- package/src/learning/reeditMiner.js +104 -0
- package/src/learning/selfImprove.js +9 -1
- package/template_project/.claude/skills/canvas-design/SKILL.md +2 -2
- package/template_project/.claude/skills/canvas-design/canvas-fonts/{InstrumentSans-OFL.txt → InstrumentSerif-OFL.txt} +3 -3
- package/template_project/.claude/skills/canvas-design/scripts/fetch-fonts.mjs +148 -0
- package/template_project/.claude/ukit/index/embed-index.mjs +26 -0
- package/template_project/.claude/ukit/index/lib/index-core.mjs +561 -14
- package/template_project/.claude/ukit/index/lib/semantic-lane.mjs +269 -0
- package/template_project/.claude/ukit/index/query-index.mjs +9 -1
- package/template_project/.claude/ukit/index/refresh-index.mjs +11 -0
- package/template_project/.claude/ukit/index/route-resolver.mjs +2 -2
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +9 -2
- package/template_project/.claude/ukit/runtime/memory-policy.mjs +5 -0
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +39 -3
- package/template_project/.claude/ukit/runtime/memory-topics.mjs +545 -0
- package/template_project/ukit/storage/config.json +19 -34
- package/manifests/instructionRules.yaml +0 -442
- package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-OFL.txt +0 -93
- package/template_project/.claude/skills/canvas-design/canvas-fonts/BricolageGrotesque-Regular.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-BoldItalic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Italic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSans-Regular.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/InstrumentSerif-Italic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/JetBrainsMono-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-BoldItalic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Italic.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-OFL.txt +0 -93
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Lora-Regular.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Outfit-Bold.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/Tektur-Medium.ttf +0 -0
- package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-OFL.txt +0 -93
- package/template_project/.claude/skills/canvas-design/canvas-fonts/YoungSerif-Regular.ttf +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,33 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to UKit are documented here.
|
|
4
4
|
|
|
5
|
+
## 3.5.6 - 2026-11-15
|
|
6
|
+
|
|
7
|
+
Cleanup release: unused modules and flags removed, the `.ukit-new` files are gone, most design fonts moved out of the package, the two learning ideas rebuilt as one small, measured step, and an opt-in vector lane for index search. Every number below was measured on this repository only. No host (Claude Code, Codex, omp) was run live and nothing was run on Windows.
|
|
8
|
+
|
|
9
|
+
- **No more `.ukit-new` files.** `docs/AI_HANDOFF/RULES.md` and `docs/AI_HANDOFF/queued/README.md` used to get a `<file>.ukit-new` copy on every install once you had edited them. They are now merged in place, section by section (`## ` headings): a section you never touched is updated to the new template, a section you edited or added is kept, and a new template section is added. Three limits: a new template section is not added when its exact heading line already appears anywhere in your file, even quoted inside a code block (this is what keeps the file from growing on repeated installs); on the first install after upgrading from 3.5.5 or older there is no record of what UKit wrote, so every section that differs from the current template is kept as if you had edited it (and reported whenever the template later changes that section); and a section whose heading was renamed is kept while the template's section under the other name is added beside it — whether you renamed it or UKit did in an earlier version. The known case is `docs/AI_HANDOFF/queued/README.md`: 3.4.66 renamed "Deliberate-future queue" to "Deliberate-future queue (backlog)" and "Mandatory overflow (consumable, not backlog)" to "Mandatory overflow (consumable)", so a copy older than 3.4.66 that you edited, or that has no recorded hash, ends up once with the old and the new version of those two sections side by side and no message printed; delete the two old sections by hand. When a section you edited also changed in the template, install prints one line naming it and keeps yours. The previous file is copied to the backup folder before any change. A leftover `.ukit-new` from an older version is removed only when its content is UKit's own (recorded hash, or identical to the shipped template); anything else is left and reported once. Checked in a temporary project: install, add a section to `RULES.md`, install twice — no `.ukit-new`, the section is kept, the later runs print nothing about the file.
|
|
10
|
+
- **Seven unused modules and nine flags removed.** `runtimeScheduler`, `runtimeFilter`, `deliberation`, `dynamicWorkflow`, `deltaOverlays`, `learningCandidates` and `resourcePolicy` had no production caller and are deleted with their tests. Their flags are gone from the default config: `decisionRuntime.scheduler`, `.context`, `.completion`, `.quality`, `.resourcePolicy`, `experiments.deliberation`, `experiments.dynamicWorkflow`, `learning.overlays`, `learning.candidates`. A config that still contains them loads without a warning; memory records written by the removed modules are still readable.
|
|
11
|
+
- **Fix: unapproved lesson proposals no longer appear in recall.** Proposals waiting for approval were stored as verified records and showed up in `ukit memory recall`. Recall now leaves them out until they are approved.
|
|
12
|
+
- **`ukit memory learn --git`: lessons from files that keep getting fixed.** Reads the commit history (it refuses a shallow clone), finds source files fixed repeatedly, and writes them as candidates only — nothing is promoted automatically, and a candidate expires after 90 days. `--dry-run` shows what would be written. Files that no longer exist are dropped. Back-test on this repository, where "the file was fixed again later" stands in for "the lesson was right" (small numbers): last 400 commits, threshold 2: 11 files flagged, 36% fixed again; threshold 3: 5 flagged, 80%; last 90 days, threshold 2: 2 flagged, both fixed again. Coverage is low (3–13% of the files fixed later). Reproduce with `node scripts/bench/learning-backtest.mjs` in the source repository. Retracting a lesson when its file changes was not tested.
|
|
13
|
+
- **`unic-decision` can screen borderline lesson candidates — off by default.** Registry key `learn.candidate-class.v1`, stage `decisionPlane.families.learn.stage` (`off` | `shadow` | on). It is asked one yes/no question per borderline candidate (at most 8, 2 s each) and can only downgrade one. Measured effect in the back-test: one question asked, one candidate dropped (36% → 40%). That is too little to turn it on by default.
|
|
14
|
+
- **Design fonts: five bundled, the rest on demand.** The `canvas-design` skill now ships five fonts (Instrument Serif, JetBrains Mono, Nothing You Could Do, Outfit, Tektur) with their licences. The others are fetched when wanted: `node .claude/skills/canvas-design/scripts/fetch-fonts.mjs --list`, then `<Family>` or `--all`. Files come from a pinned commit of `google/fonts` and are checked by SHA-256 before they are written. Fetched variable fonts are saved as `<Family>-Variable.ttf`. An existing install keeps the fonts it already has (read from the code, not run on an old install).
|
|
15
|
+
- **Index search: opt-in vector lane for plain-language questions.** Off unless you set `UKIT_INDEX_EMBED_URL` to an OpenAI-compatible embeddings endpoint (`…/v1` or `…/v1/embeddings`; optional `UKIT_INDEX_EMBED_MODEL`, `UKIT_INDEX_EMBED_KEY`). With no URL nothing runs and nothing leaves the machine. **Privacy:** building vectors sends one short descriptor per indexed file (path, symbol names, leading comment, at most 240 characters) to that endpoint, and each question sends the question text; the build command prints the endpoint host first, and `.env`, key and credential files are never sent. Build with `node .claude/ukit/index/embed-index.mjs` — an explicit command, never part of index build, refresh or any hook. Vectors are stored in `.cache/index/semantic.bin` (int8) and reused by content hash, so a rerun only embeds changed files. `ukit index query` and `query-index.mjs` use the lane only for plain-language questions (four words or more, no path, identifier or error text) whose keyword result is not already clear, wait at most 1.5 s for the endpoint, and fall back to the keyword result on any error. Files gone from the index are never returned. Measured with a local Qwen3-Embedding-4B endpoint (1,536 dimensions) on a sealed set of 39 questions never used for tuning (40 in 3.5.5; one Vietnamese question, `bv04`, was dropped because its only expected file, `resourcePolicy.js`, is deleted in this release; it was not a top-3 hit in 3.5.5. Without the lane, Vietnamese top 3 is 3/19 here against 4/20 in 3.5.5 because one other question moved from rank 3 to rank 4): answer in top 3 from 5 to 21, in top 10 from 9 to 32 (English 20 questions: top 3 2 → 11; Vietnamese 19 questions: top 3 3 → 10); top 1 from 3 to 11. Cost: about 655 ms per question against 59 ms without the lane (machine under load), a 3.7 MB cache for 2,424 files, and a first build of 666 s measured while the machine was short of memory; a later rerun embedded 14 changed files in 5 s. An earlier fusion setting scored higher on Vietnamese (top 3 13) and lower on English (top 3 4); the shipped one is the better total. Embedding file bodies instead of descriptors was tried and not shipped (over an hour to build on this endpoint). Tested against one endpoint and one model only; hooks never use the lane.
|
|
16
|
+
|
|
17
|
+
## 3.5.5 - 2026-11-15
|
|
18
|
+
|
|
19
|
+
Module pages for memory, symbols for eight more languages, and a Vietnamese-to-code vocabulary for index search. Every number below was measured on this repository only. Finding a file from an ordinary question is still weak, and this entry says so with numbers.
|
|
20
|
+
|
|
21
|
+
- **Module pages (`ukit memory topic build|list|show|check`).** `ukit memory topic build <dir>` writes `docs/memory/topics/<dir>.md`: the directory's key files, what they export and the memory notes that name them. Recall reads the pages (`memory.topics.recall`, default on) and labels a page whose directory changed since it was built; the edit hint names the page of the file being edited (`memory.topics.hint`, default on). Nothing happens until a page exists. An index refresh rebuilds existing pages that went stale (`UKIT_MEMORY_TOPICS=0` turns the feature off). Measured on 12 questions about a module: 0 answered in the top 3 without pages, 10 with pages; under the stricter scoring 7. The main memory gold set is unchanged (37/38 answered, 10/10 no-answer questions stay silent). Pages are never read or written through a symbolic link, a module directory that is a link or leaves the project is refused, and a page is written to a temporary file and renamed. The rebuild on index refresh is covered by tests and was not exercised through a real git hook.
|
|
22
|
+
- **Symbols for Python, Go, Java, C#, PHP, Ruby, Rust and Svelte.** Functions, classes, methods and types in these files are now indexed (line-based parsers, no new dependency), their test files are recognised (`_test.go`, `test_*.py`, `*Test.java`, `_spec.rb` and similar), and the error-text search reads them. Covered by unit tests on small fixtures; in this repository only Python files exist (219 symbols). No real project in the other languages was indexed. These parsers skip files over 512 KB and lines over 2,000 characters, so a hostile file cannot stall the build. Known limit: a C# method whose attribute is on the same line as its declaration (`[HttpGet] public Task<IActionResult> Get(…)`) is not indexed as a symbol; put the attribute on its own line, as most C# code does. Java annotations on the same line are indexed. The index schema version is now 11: the first build after the update re-parses every file once.
|
|
23
|
+
- **Fewer wrong `callable` symbols.** `const x = (…)` expressions that are not functions are no longer marked callable (465 → 16 by the build's own count), and about 50 real functions the old rule missed are now found.
|
|
24
|
+
- **Vietnamese questions map to code words.** About 60 Vietnamese phrases and words (diacritics optional) expand to the English terms used in code, and questions of five or more words also match word stems. On the 67-query gold set (floor now `scripts/bench/baselines/index-gold-3.5.5.json`): right file first 86.6% → 89.5%, top 3 unchanged at 92.5%; English sentence first 72.7 → 81.8, Vietnamese sentence first 50 → 60; no group lower.
|
|
25
|
+
- **Honest limit: ordinary questions still rarely find the file.** On a sealed set of 40 questions written by a separate agent and never shown to the people tuning the search (`scripts/bench/indexBlind.json`, 20 English + 20 Vietnamese), the right file is in the top 3 for English 3/20 in 3.5.4 → 2/20 now, for Vietnamese 2/20 → 4/20 (5/20 on an earlier state of this tree: one question sits at the edge of the top 3). The gold-set gain above is therefore partly fitted to its own questions. Searching by symbol name, path or error text is unaffected (100 / 100 / 90% first).
|
|
26
|
+
- **Built, measured, not shipped:** a per-file description text (leading comments) used to re-rank results changed nothing on the sealed set, and 144 ways of letting it propose files lowered the gold set — the code was removed. Adding symbol evidence to test hints moved recall from 0.072 to 0.079, which is noise — no change.
|
|
27
|
+
- **Shipped off by default, because the numbers did not rise:** index lane fusion (`index.fusion`, `UKIT_INDEX_FUSION=1`); a hashed vector lane for memory recall (`memory.recall.vector.enabled`; with it on, memory gold fell from 37/38 to 35/38); re-ranking recall with the local `unic-decision` model (`memory.recall.rerank.stage`, registry entry `memory.relevance.v1`; no change in results, measured in one live batch before the final recall code). No embedding endpoint is configured, so no real semantic lane was measured.
|
|
28
|
+
- **Recall understands a file name in the question.** A question that names a file only returns notes about that file, and camelCase words in a question are split. On 12 questions that name a file or symbol: 11 answered, and all 4 with no answer stay silent.
|
|
29
|
+
- Package: `manifests/instructionRules.yaml` (read only by tests) is no longer packed; 728 files, 3.46 MB packed, 11.22 MB unpacked (limits unchanged, about 80 KB of headroom).
|
|
30
|
+
- Engines: pages, recall and index code are shared runtime and CLI code used by Claude Code, omp (through the bridge) and Codex (through the CLI helpers). None of the three hosts was run live for this release, and nothing was run on Windows.
|
|
31
|
+
|
|
5
32
|
## 3.5.4 - 2026-11-15
|
|
6
33
|
|
|
7
34
|
The index now knows almost every function and can search file contents for error text; memory writes pass a gate and `docs/MEMORY.md` becomes a capped core. Every number below was measured on this repository only.
|
|
@@ -56,22 +56,9 @@ classes:
|
|
|
56
56
|
codex: { support: degraded, note: 'no session-start/stop hooks; resume record is advisory context, never auto-reinjected' }
|
|
57
57
|
omp: { support: enforced, evidence: tests/hooks/reinjectContextHook.test.js }
|
|
58
58
|
promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
|
|
59
|
-
learning-overlays:
|
|
60
|
-
hosts:
|
|
61
|
-
claude-code: { support: enforced, evidence: tests/core/deltaOverlays.test.js }
|
|
62
|
-
codex: { support: degraded, note: 'overlay approval gate lives in shared runtime; codex consumes rendered policy without a hook gate' }
|
|
63
|
-
omp: { support: enforced, evidence: tests/core/deltaOverlays.test.js }
|
|
64
|
-
promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
|
|
65
59
|
advisory:
|
|
66
60
|
description: stdout/prompt text the model is asked to respect (routes, suppress, budgets)
|
|
67
61
|
hosts:
|
|
68
62
|
claude-code: { support: advisory }
|
|
69
63
|
codex: { support: advisory }
|
|
70
64
|
omp: { support: advisory }
|
|
71
|
-
mechanisms:
|
|
72
|
-
experiment-flags:
|
|
73
|
-
hosts:
|
|
74
|
-
claude-code: { support: advisory }
|
|
75
|
-
codex: { support: advisory }
|
|
76
|
-
omp: { support: advisory }
|
|
77
|
-
promotionEvidence: { stage: off, evaluatedAt: null, verdict: not-evaluated, evidenceRef: null }
|
|
@@ -1806,6 +1806,18 @@ items:
|
|
|
1806
1806
|
type: config
|
|
1807
1807
|
sourceTemplate: .claude/ukit/index/lib/index-core.mjs
|
|
1808
1808
|
targetPath: .claude/ukit/index/lib/index-core.mjs
|
|
1809
|
+
requires:
|
|
1810
|
+
- ukit-index-semantic-lane-lib
|
|
1811
|
+
mergeStrategy: overwrite_with_backup
|
|
1812
|
+
variables: []
|
|
1813
|
+
enabledByDefault: true
|
|
1814
|
+
packs:
|
|
1815
|
+
- core
|
|
1816
|
+
|
|
1817
|
+
- id: ukit-index-semantic-lane-lib
|
|
1818
|
+
type: config
|
|
1819
|
+
sourceTemplate: .claude/ukit/index/lib/semantic-lane.mjs
|
|
1820
|
+
targetPath: .claude/ukit/index/lib/semantic-lane.mjs
|
|
1809
1821
|
requires: []
|
|
1810
1822
|
mergeStrategy: overwrite_with_backup
|
|
1811
1823
|
variables: []
|
|
@@ -1813,6 +1825,19 @@ items:
|
|
|
1813
1825
|
packs:
|
|
1814
1826
|
- core
|
|
1815
1827
|
|
|
1828
|
+
- id: ukit-index-embed-script
|
|
1829
|
+
type: config
|
|
1830
|
+
sourceTemplate: .claude/ukit/index/embed-index.mjs
|
|
1831
|
+
targetPath: .claude/ukit/index/embed-index.mjs
|
|
1832
|
+
requires:
|
|
1833
|
+
- ukit-index-core-lib
|
|
1834
|
+
- ukit-index-semantic-lane-lib
|
|
1835
|
+
mergeStrategy: overwrite_with_backup
|
|
1836
|
+
variables: []
|
|
1837
|
+
enabledByDefault: true
|
|
1838
|
+
packs:
|
|
1839
|
+
- core
|
|
1840
|
+
|
|
1816
1841
|
- id: ukit-index-build-script
|
|
1817
1842
|
type: config
|
|
1818
1843
|
sourceTemplate: .claude/ukit/index/build-index.mjs
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ngockhoale/ukit",
|
|
3
|
-
"version": "3.5.
|
|
3
|
+
"version": "3.5.6",
|
|
4
4
|
"description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -63,11 +63,6 @@
|
|
|
63
63
|
"!src/core/agentRuntime/runtimeSupport.js",
|
|
64
64
|
"!src/core/agentRuntime/completionGate.js",
|
|
65
65
|
"!src/core/agentRuntime/qualityComparison.js",
|
|
66
|
-
"!src/core/agentRuntime/resourcePolicy.js",
|
|
67
|
-
"!src/core/memory/deltaOverlays.js",
|
|
68
|
-
"!src/core/memory/learningCandidates.js",
|
|
69
|
-
"!src/core/experiments/dynamicWorkflow.js",
|
|
70
|
-
"!src/core/experiments/deliberation.js",
|
|
71
66
|
"!src/core/observability/evaluation/scorecard.js",
|
|
72
67
|
"!src/core/observability/evaluation/replay.js",
|
|
73
68
|
"!src/core/observability/emit/sessionBoot.js",
|
|
@@ -83,8 +78,6 @@
|
|
|
83
78
|
"!src/index/contextPack.js",
|
|
84
79
|
"!src/index/sensitivePath.js",
|
|
85
80
|
"!src/decision/reviewVerdict.js",
|
|
86
|
-
"!src/decision/runtimeScheduler.js",
|
|
87
|
-
"!src/decision/runtimeFilter.js",
|
|
88
81
|
"!scripts/bench/**",
|
|
89
82
|
"scripts/bench/decision-runtime-metrics.mjs",
|
|
90
83
|
"!scripts/perf/**",
|
|
@@ -97,7 +90,8 @@
|
|
|
97
90
|
"!template_project/**/skill-router-state.json",
|
|
98
91
|
"CHANGELOG.md",
|
|
99
92
|
"template_project/.gitignore",
|
|
100
|
-
"manifests/"
|
|
93
|
+
"manifests/",
|
|
94
|
+
"!manifests/instructionRules.yaml"
|
|
101
95
|
],
|
|
102
96
|
"publishConfig": {
|
|
103
97
|
"access": "public"
|
|
@@ -25,7 +25,7 @@ import { redactWritePayload } from '../../core/memory/writeGuard.js';
|
|
|
25
25
|
import { checkProposalText } from '../../core/memory/writeGate.js';
|
|
26
26
|
import { deletePromptCacheEntries } from '../../core/token/index.js';
|
|
27
27
|
import { expand, getContextInjection, search } from '../../core/memory/retrieval.js';
|
|
28
|
-
import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
|
|
28
|
+
import { inspectRuntimeConfig, loadRuntimeConfig } from '../../core/runtimeConfig.js';
|
|
29
29
|
import { buildRuntimePaths } from '../../core/runtimePaths.js';
|
|
30
30
|
import { buildUserPaths } from '../../core/userPaths.js';
|
|
31
31
|
import { pathExists } from '../../core/fileOps.js';
|
|
@@ -758,6 +758,16 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
758
758
|
return;
|
|
759
759
|
}
|
|
760
760
|
|
|
761
|
+
// 3.5.5: topic pages (docs/memory/topics/*.md) are generated from the index and
|
|
762
|
+
// the edit graph; build/list/show/check need no runtime gate.
|
|
763
|
+
if (subcommand === 'topic') {
|
|
764
|
+
const { runTopicCommand } = await import('../../core/memory/topicCommand.js');
|
|
765
|
+
const res = await runTopicCommand(projectRoot, rest);
|
|
766
|
+
console.log(res.output);
|
|
767
|
+
if (!res.ok) process.exitCode = 1;
|
|
768
|
+
return;
|
|
769
|
+
}
|
|
770
|
+
|
|
761
771
|
// --user operates on ~/.ukit and does not require the project runtime.
|
|
762
772
|
if (!isUser && !(await pathExists(runtimePaths.runtimeRoot))) {
|
|
763
773
|
throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
|
|
@@ -844,7 +854,12 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
844
854
|
|
|
845
855
|
if (subcommand === 'learn') {
|
|
846
856
|
const applyFlag = rest.includes('--apply');
|
|
847
|
-
const
|
|
857
|
+
const gitFlag = rest.includes('--git');
|
|
858
|
+
// --dry-run is an explicit no-op alias of the default (preview only).
|
|
859
|
+
if (applyFlag && rest.includes('--dry-run')) {
|
|
860
|
+
throw new Error('memory learn: --dry-run and --apply are mutually exclusive');
|
|
861
|
+
}
|
|
862
|
+
const knownFlags = new Set(['--apply', '--git', '--dry-run']);
|
|
848
863
|
const minFlag = extractFlag(rest, '--min');
|
|
849
864
|
const projectFlag = extractFlag(minFlag.rest, '--project');
|
|
850
865
|
for (const arg of projectFlag.rest) {
|
|
@@ -858,11 +873,31 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
858
873
|
}
|
|
859
874
|
const projectId = projectFlag.value ?? (await detectProjectContext(projectRoot, { homeDir })).project.name;
|
|
860
875
|
|
|
861
|
-
const { proposeFromPatterns } = await import('../../learning/patternProposals.js');
|
|
876
|
+
const { proposeFromPatterns, proposeFromReedits } = await import('../../learning/patternProposals.js');
|
|
877
|
+
// Decision plane (unic-decision) only refines the ambiguous cases, downgrade-only;
|
|
878
|
+
// stage off (default) or an unreachable provider leaves the rule result.
|
|
879
|
+
const { resolveLessonStage, createLessonClient } = await import('../../learning/lessonClass.js');
|
|
880
|
+
const learnConfig = await loadRuntimeConfig(projectRoot, { homeDir }).catch(() => null);
|
|
881
|
+
const stage = resolveLessonStage(learnConfig);
|
|
882
|
+
const client = createLessonClient({ config: learnConfig, projectRoot, homeDir });
|
|
862
883
|
const result = await proposeFromPatterns(projectRoot, projectId, {
|
|
863
884
|
minCount,
|
|
864
885
|
dryRun: !applyFlag,
|
|
886
|
+
client,
|
|
887
|
+
stage,
|
|
865
888
|
});
|
|
889
|
+
if (gitFlag) {
|
|
890
|
+
// Explicit command only: spawns git, so never part of a hook path.
|
|
891
|
+
const { mineGitReedits } = await import('../../learning/reeditMiner.js');
|
|
892
|
+
const reedits = await mineGitReedits(projectRoot, { minFixes: minCount ?? 3 });
|
|
893
|
+
const git = await proposeFromReedits(projectRoot, projectId, { reedits, dryRun: !applyFlag, client, stage });
|
|
894
|
+
if (git.decision && result.decision) {
|
|
895
|
+
for (const k of ['asked', 'answered', 'changed']) result.decision[k] += git.decision[k];
|
|
896
|
+
}
|
|
897
|
+
result.proposed.push(...git.proposed);
|
|
898
|
+
result.eligible += git.proposed.filter((p) => p.status !== 'skipped').length;
|
|
899
|
+
if (git.error && !result.error) result.error = git.error;
|
|
900
|
+
}
|
|
866
901
|
if (result.error) {
|
|
867
902
|
console.log(`[UKit] memory learn: ${result.error}`);
|
|
868
903
|
}
|
|
@@ -883,6 +918,10 @@ export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = []
|
|
|
883
918
|
console.log(` [${entry.status}] ${entry.signature} — ${entry.text}`);
|
|
884
919
|
}
|
|
885
920
|
console.log(`[UKit] memory learn: proposed ${proposed}, duplicate ${duplicates}, skipped ${skipped} for project ${projectId}.`);
|
|
921
|
+
if (result.decision && result.decision.stage !== 'off') {
|
|
922
|
+
const d = result.decision;
|
|
923
|
+
console.log(`[UKit] decision plane (stage ${d.stage}): asked ${d.asked}, answered ${d.answered}, changed ${d.changed}${d.answered === 0 && d.asked > 0 ? ' (provider gave no valid answer; rule results kept)' : ''}.`);
|
|
924
|
+
}
|
|
886
925
|
if (proposed > 0) {
|
|
887
926
|
console.log('[UKit] Review with `ukit memory list --pending`, then `ukit memory approve <id>`.');
|
|
888
927
|
}
|
|
@@ -1118,9 +1157,10 @@ export function printMemoryHelp() {
|
|
|
1118
1157
|
console.log(' propose "<text>" [--category <name>] [--project <id>] Propose a project convention for human approval');
|
|
1119
1158
|
console.log(' approve <id> [--project <id>] Approve a pending pattern candidate into project conventions');
|
|
1120
1159
|
console.log(' reject <id> [--project <id>] Reject a pending pattern candidate');
|
|
1121
|
-
console.log(' learn [--apply] [--min <n>] [--project <id>] Propose pending candidates from
|
|
1160
|
+
console.log(' learn [--apply|--dry-run] [--git] [--min <n>] [--project <id>] Propose pending candidates from failure patterns, and with --git from files that keep needing fix commits (preview is the default; --apply writes)');
|
|
1122
1161
|
console.log(' promote [--dry-run] Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
|
|
1123
1162
|
console.log(' episode [--dry-run] [--session <id>|--start] Write a session episode record from the exec-ledger');
|
|
1163
|
+
console.log(' topic build <dir>|list|show <dir>|check Module pages under docs/memory/topics (generated skeleton; stale when the directory changed)');
|
|
1124
1164
|
console.log(' observe [--min <n>] [--json] Propose observations from repeated content-bearing episodes (proposals only; nothing is written)');
|
|
1125
1165
|
console.log(' check [--json] [--file <rel>] Check docs/MEMORY.md + memory.sources against the memory rules (core cap, size, secrets, near-duplicates, supersession); exit 1 on violations');
|
|
1126
1166
|
console.log(' archive-episodes [--dry-run|--restore] Move content-free legacy episodes to episodes-archive.json (backup first; --restore re-adds them)');
|
package/src/core/applyPlan.js
CHANGED
|
@@ -105,95 +105,48 @@ export async function pruneOldBackups(backupRoot, {
|
|
|
105
105
|
return { scanned: files.length, removed };
|
|
106
106
|
}
|
|
107
107
|
|
|
108
|
-
//
|
|
109
|
-
//
|
|
110
|
-
//
|
|
111
|
-
|
|
112
|
-
// current hash; otherwise preserve and report a conflict.
|
|
113
|
-
async function writeManagedTemplateSidecar(sidecarPath, content, recordedSidecarHash) {
|
|
114
|
-
const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
|
|
115
|
-
const nextHash = sha256Hex(bytes);
|
|
116
|
-
const state = await readSidecarState(sidecarPath);
|
|
117
|
-
|
|
118
|
-
if (state.state === 'absent') {
|
|
119
|
-
try {
|
|
120
|
-
await writeFileExclusive(sidecarPath, content);
|
|
121
|
-
return nextHash;
|
|
122
|
-
} catch (error) {
|
|
123
|
-
if (error?.code === 'EEXIST') {
|
|
124
|
-
// Lost the race to an owner file — never overwrite it.
|
|
125
|
-
console.warn(`[UKit] Warning: ${sidecarPath} appeared during install; left untouched (possible owner content).`);
|
|
126
|
-
return null;
|
|
127
|
-
}
|
|
128
|
-
throw error;
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
if (state.state === 'file' && typeof recordedSidecarHash === 'string' && recordedSidecarHash === state.hash) {
|
|
132
|
-
if (state.hash === nextHash) {
|
|
133
|
-
return nextHash; // already the current template — nothing to write
|
|
134
|
-
}
|
|
135
|
-
// Re-verify immediately before the rename: an owner edit landing between the
|
|
136
|
-
// first read and this write must not be silently replaced (TOCTOU window).
|
|
137
|
-
const recheck = await readSidecarState(sidecarPath);
|
|
138
|
-
if (recheck.state !== 'file' || recheck.hash !== recordedSidecarHash) {
|
|
139
|
-
console.warn(`[UKit] Warning: ${sidecarPath} changed during install; left untouched (possible owner content).`);
|
|
140
|
-
return null;
|
|
141
|
-
}
|
|
142
|
-
await writeFileAtomic(sidecarPath, content);
|
|
143
|
-
return nextHash;
|
|
144
|
-
}
|
|
145
|
-
// Owner-authored, owner-modified, symlink, or unreadable sidecar: keep it.
|
|
146
|
-
console.warn(
|
|
147
|
-
`[UKit] Warning: ${sidecarPath} is not UKit-managed (${state.state === 'file' ? 'content changed since UKit wrote it' : state.state}); preserved. Review it manually.`,
|
|
148
|
-
);
|
|
149
|
-
return null;
|
|
150
|
-
}
|
|
151
|
-
|
|
152
|
-
// Removes a sidecar only when install.json recorded the hash that is on disk now.
|
|
153
|
-
// Unrecorded/owner-modified/symlink sidecars are preserved and reported.
|
|
154
|
-
async function removeManagedTemplateSidecar(sidecarPath, recordedSidecarHash) {
|
|
108
|
+
// Legacy `.ukit-new` cleanup (sidecars are no longer written). A leftover is removed only when
|
|
109
|
+
// UKit can attribute it: install.json recorded its hash, or its bytes equal a UKit template
|
|
110
|
+
// render for that file. Anything else is left in place and reported once.
|
|
111
|
+
async function removeLegacySidecar(sidecarPath, recordedSidecarHash, templateRender) {
|
|
155
112
|
const state = await readSidecarState(sidecarPath);
|
|
156
113
|
if (state.state === 'absent') {
|
|
157
114
|
return true;
|
|
158
115
|
}
|
|
159
|
-
|
|
116
|
+
const templateHash = templateRender === undefined || templateRender === null
|
|
117
|
+
? null
|
|
118
|
+
: sha256Hex(Buffer.isBuffer(templateRender) ? templateRender : Buffer.from(templateRender, 'utf8'));
|
|
119
|
+
const recorded = typeof recordedSidecarHash === 'string' && recordedSidecarHash === state.hash;
|
|
120
|
+
if (state.state === 'file' && (recorded || (templateHash !== null && templateHash === state.hash))) {
|
|
160
121
|
await fs.rm(sidecarPath, { force: true });
|
|
161
122
|
return true;
|
|
162
123
|
}
|
|
163
124
|
console.warn(
|
|
164
|
-
`[UKit]
|
|
125
|
+
`[UKit] Note: ${sidecarPath} is a leftover from an older UKit but its content is not UKit's own; left in place. Delete it when no longer needed.`,
|
|
165
126
|
);
|
|
166
127
|
return false;
|
|
167
128
|
}
|
|
168
129
|
|
|
169
|
-
export async function applyDiffResults(diffResults, { backupRoot, projectRoot, recordedSidecarHashes = null,
|
|
130
|
+
export async function applyDiffResults(diffResults, { backupRoot, projectRoot, recordedSidecarHashes = null, packageVersion = null } = {}) {
|
|
170
131
|
const writes = [];
|
|
171
132
|
let skippedUpdates = 0;
|
|
172
133
|
const skippedByAction = { create: 0, update: 0 };
|
|
173
134
|
|
|
174
135
|
for (const entry of diffResults) {
|
|
175
|
-
//
|
|
176
|
-
//
|
|
177
|
-
if (entry.
|
|
136
|
+
// Managed templates: clean up attributable `.ukit-new` leftovers from older versions, and
|
|
137
|
+
// surface section notices (the merge itself was computed in diffPlan).
|
|
138
|
+
if (entry.mergeStrategy === 'managed_template' && entry.type !== 'link') {
|
|
178
139
|
const sidecarPath = `${entry.targetPath}.ukit-new`;
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
console.log(`[UKit] Kept your edited ${path.basename(entry.targetPath)} unchanged; the new UKit template is at ${path.basename(sidecarPath)} — review and merge it.`);
|
|
184
|
-
} else {
|
|
185
|
-
console.log(`[UKit] Kept your edited ${path.basename(entry.targetPath)} unchanged; an owner file already exists at ${path.basename(sidecarPath)} and was preserved.`);
|
|
186
|
-
}
|
|
187
|
-
skippedUpdates += 1;
|
|
188
|
-
skippedByAction.update += 1;
|
|
189
|
-
continue;
|
|
190
|
-
}
|
|
191
|
-
if (entry.action === 'unchanged' && entry.removeSidecar) {
|
|
192
|
-
// Only a UKit-generated, unmodified sidecar is cleaned up; owner files stay.
|
|
193
|
-
await removeManagedTemplateSidecar(
|
|
194
|
-
`${entry.targetPath}.ukit-new`,
|
|
195
|
-
recordedSidecarHashes?.get(`${entry.targetPath}.ukit-new`) ?? null,
|
|
140
|
+
await removeLegacySidecar(
|
|
141
|
+
sidecarPath,
|
|
142
|
+
recordedSidecarHashes?.get(sidecarPath) ?? null,
|
|
143
|
+
entry.templateRender ?? entry.renderedContent,
|
|
196
144
|
);
|
|
145
|
+
for (const notice of entry.mergeNotices ?? []) {
|
|
146
|
+
console.log(
|
|
147
|
+
`[UKit] ${path.basename(entry.targetPath)}: kept your edited section "${notice.heading}"; the UKit template for it changed${packageVersion ? ` in ${packageVersion}` : ''}.`,
|
|
148
|
+
);
|
|
149
|
+
}
|
|
197
150
|
}
|
|
198
151
|
if (entry.action !== 'create' && entry.action !== 'update') {
|
|
199
152
|
continue;
|
|
@@ -243,7 +196,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, r
|
|
|
243
196
|
// Back up the existing file before overwriting
|
|
244
197
|
if (
|
|
245
198
|
entry.action === 'update' &&
|
|
246
|
-
(entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup') &&
|
|
199
|
+
(entry.mergeStrategy === 'overwrite_with_backup' || entry.mergeStrategy === 'merge_env_overwrite_with_backup' || entry.mergeStrategy === 'managed_template') &&
|
|
247
200
|
backupRoot &&
|
|
248
201
|
projectRoot
|
|
249
202
|
) {
|
|
@@ -333,5 +286,5 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot, r
|
|
|
333
286
|
});
|
|
334
287
|
}
|
|
335
288
|
|
|
336
|
-
return { writes, skippedUpdates, skippedByAction
|
|
289
|
+
return { writes, skippedUpdates, skippedByAction };
|
|
337
290
|
}
|
package/src/core/diffPlan.js
CHANGED
|
@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
|
|
|
3
3
|
import YAML from 'yaml';
|
|
4
4
|
import { isSymlinkTo } from './fileOps.js';
|
|
5
5
|
import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
|
|
6
|
+
import { mergeManagedTemplate, sectionHashes } from './managedTemplateMerge.js';
|
|
6
7
|
import { isOmpConfigTarget, mergeOmpConfig } from './ompConfigMerge.js';
|
|
7
8
|
import { mergeOmpProjectConfig } from './ompProjectConfig.js';
|
|
8
9
|
import { mergeRuntimeConfigText } from './runtimeConfigMerge.js';
|
|
@@ -15,12 +16,13 @@ const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAU
|
|
|
15
16
|
// look identical to "missing" and the apply step would either overwrite the
|
|
16
17
|
// live file atomically with no .bak (W2-C4) or crash mid-install on a 'wx'
|
|
17
18
|
// create (W2-C6). Unreadable targets get a non-write action instead.
|
|
18
|
-
// CR-13: managed AI_HANDOFF templates.
|
|
19
|
+
// CR-13: managed AI_HANDOFF templates. Replace only when the installed file is still the
|
|
19
20
|
// content UKit last recorded (its sha256 in install.json); an owner-edited or legacy
|
|
20
|
-
// (no recorded hash) file
|
|
21
|
+
// (no recorded hash) file is merged by `## ` section (see managedTemplateMerge.js) — no
|
|
22
|
+
// sidecar file is ever written.
|
|
21
23
|
const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
|
|
22
24
|
|
|
23
|
-
async function resolveManagedTemplateAction(entry, recordedHashes) {
|
|
25
|
+
async function resolveManagedTemplateAction(entry, recordedHashes, recordedSections = null) {
|
|
24
26
|
const template = Buffer.isBuffer(entry.renderedContent) ? entry.renderedContent : Buffer.from(entry.renderedContent, 'utf8');
|
|
25
27
|
const templateHash = sha256(template);
|
|
26
28
|
|
|
@@ -42,20 +44,43 @@ async function resolveManagedTemplateAction(entry, recordedHashes) {
|
|
|
42
44
|
const read = await readFileOrStatus(entry.targetPath, null);
|
|
43
45
|
if (read.status === 'missing') {
|
|
44
46
|
// ONLY a confirmed absence permits create; unreadable must never overwrite.
|
|
45
|
-
return {
|
|
47
|
+
return {
|
|
48
|
+
...entry, exists: false, action: 'create', existingContent: null, managedHash: templateHash,
|
|
49
|
+
managedSections: sectionHashes(template.toString('utf8'), { markdown: /\.md$/i.test(entry.targetPath) }),
|
|
50
|
+
};
|
|
46
51
|
}
|
|
47
52
|
if (read.status !== 'ok') {
|
|
48
53
|
return conflictResult(entry, read.error);
|
|
49
54
|
}
|
|
50
55
|
const installed = read.content;
|
|
51
56
|
const installedHash = sha256(installed);
|
|
57
|
+
const markdown = /\.md$/i.test(entry.targetPath);
|
|
58
|
+
const templateText = template.toString('utf8');
|
|
59
|
+
const managedSections = sectionHashes(templateText, { markdown });
|
|
52
60
|
if (installedHash === templateHash) {
|
|
53
|
-
return { ...entry, exists: true, action: 'unchanged', existingContent: installed, managedHash: templateHash,
|
|
61
|
+
return { ...entry, exists: true, action: 'unchanged', existingContent: installed, managedHash: templateHash, managedSections };
|
|
54
62
|
}
|
|
55
63
|
if (recordedHashes?.get(entry.targetPath) === installedHash) {
|
|
56
|
-
return { ...entry, exists: true, action: 'update', existingContent: installed, managedHash: templateHash,
|
|
64
|
+
return { ...entry, exists: true, action: 'update', existingContent: installed, managedHash: templateHash, managedSections };
|
|
65
|
+
}
|
|
66
|
+
// Owner-edited (or legacy, no recorded hash): merge by section, never a sidecar.
|
|
67
|
+
const merged = mergeManagedTemplate({
|
|
68
|
+
existing: installed.toString('utf8'),
|
|
69
|
+
template: templateText,
|
|
70
|
+
recorded: recordedSections?.get(entry.targetPath) ?? null,
|
|
71
|
+
markdown,
|
|
72
|
+
});
|
|
73
|
+
const base = { ...entry, exists: true, existingContent: installed, managedSections: merged.sections, mergeNotices: merged.notices };
|
|
74
|
+
if (!merged.changed) {
|
|
75
|
+
return { ...base, action: 'unchanged', managedHash: null };
|
|
57
76
|
}
|
|
58
|
-
|
|
77
|
+
const mergedBuf = Buffer.from(merged.content, 'utf8');
|
|
78
|
+
return {
|
|
79
|
+
...base,
|
|
80
|
+
action: 'update',
|
|
81
|
+
renderedContent: mergedBuf,
|
|
82
|
+
managedHash: sha256(mergedBuf) === templateHash ? templateHash : null,
|
|
83
|
+
};
|
|
59
84
|
}
|
|
60
85
|
|
|
61
86
|
async function readFileOrStatus(filePath, encoding = 'utf8') {
|
|
@@ -402,7 +427,7 @@ async function resolveSkipEntryAction(entry, ompOwnership = null) {
|
|
|
402
427
|
return resolveFileAction(entry, read.content, ompOwnership);
|
|
403
428
|
}
|
|
404
429
|
|
|
405
|
-
export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null, recordedManagedHashes = null } = {}) {
|
|
430
|
+
export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigration = null, recordedManagedHashes = null, recordedManagedSections = null } = {}) {
|
|
406
431
|
// Check all entries in parallel
|
|
407
432
|
const results = await Promise.all(
|
|
408
433
|
plan.entries.map(async (entry) => {
|
|
@@ -416,7 +441,11 @@ export async function diffInstallPlan(plan, { ompOwnership = null, settingsMigra
|
|
|
416
441
|
}
|
|
417
442
|
|
|
418
443
|
if (entry.mergeStrategy === 'managed_template') {
|
|
419
|
-
|
|
444
|
+
// templateRender keeps the pristine template bytes (renderedContent may become the merge result).
|
|
445
|
+
return {
|
|
446
|
+
...(await resolveManagedTemplateAction(entry, recordedManagedHashes, recordedManagedSections)),
|
|
447
|
+
templateRender: entry.renderedContent,
|
|
448
|
+
};
|
|
420
449
|
}
|
|
421
450
|
|
|
422
451
|
const read = await readFileOrStatus(
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
|
|
3
|
+
// Section-level merge for `managed_template` files (replaces the old `.ukit-new` sidecar).
|
|
4
|
+
// A file is split by `## ` headings (outside code fences); the text before the first heading
|
|
5
|
+
// is the preamble (key ''). `recorded` is the per-section hash map UKit stored at the last
|
|
6
|
+
// install (the template's sections at that time), or null when none exists yet.
|
|
7
|
+
|
|
8
|
+
const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
|
|
9
|
+
const normalizeEol = (text) => text.replace(/\r\n/g, '\n');
|
|
10
|
+
const hashOf = (raw) => sha256(raw.trimEnd());
|
|
11
|
+
|
|
12
|
+
let sectioned = true; // set per call; non-markdown managed files are one whole-file section
|
|
13
|
+
|
|
14
|
+
// CommonMark fences: an opener is <=3 spaces + 3+ backticks/tildes (a backtick opener's info
|
|
15
|
+
// string may not contain a backtick); it closes only on the same character, at least the same
|
|
16
|
+
// length, with nothing but whitespace after. An UNCLOSED opener is treated as plain text, not a
|
|
17
|
+
// fence: CommonMark would run it to end of file, which would hide every later heading and make
|
|
18
|
+
// the merge re-append template sections on each run. Returns fenceAt[i] = line i is inside/on a fence.
|
|
19
|
+
function fenceMap(lines) {
|
|
20
|
+
const fenceAt = new Array(lines.length).fill(false);
|
|
21
|
+
for (let i = 0; i < lines.length; i += 1) {
|
|
22
|
+
const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(lines[i]);
|
|
23
|
+
if (!open || (open[1][0] === '`' && open[2].includes('`'))) continue;
|
|
24
|
+
const ch = open[1][0];
|
|
25
|
+
const len = open[1].length;
|
|
26
|
+
const closer = new RegExp(`^ {0,3}\\${ch}{${len},}\\s*$`);
|
|
27
|
+
let end = -1;
|
|
28
|
+
for (let j = i + 1; j < lines.length; j += 1) {
|
|
29
|
+
if (closer.test(lines[j])) { end = j; break; }
|
|
30
|
+
}
|
|
31
|
+
if (end === -1) { // unclosed: not a fence, but everything after it is suspect (see mergeManagedTemplate)
|
|
32
|
+
if (fenceAt.unclosedFrom === undefined) fenceAt.unclosedFrom = i;
|
|
33
|
+
continue;
|
|
34
|
+
}
|
|
35
|
+
for (let k = i; k <= end; k += 1) fenceAt[k] = true;
|
|
36
|
+
i = end;
|
|
37
|
+
}
|
|
38
|
+
return fenceAt;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function parseSections(lfText) {
|
|
42
|
+
if (!sectioned) return [{ key: '', raw: lfText }];
|
|
43
|
+
const lines = lfText.split('\n');
|
|
44
|
+
const sections = [{ key: '', raw: '' }];
|
|
45
|
+
const seen = new Map();
|
|
46
|
+
const fenceAt = fenceMap(lines);
|
|
47
|
+
lines.forEach((line, i) => {
|
|
48
|
+
const text = i < lines.length - 1 ? `${line}\n` : line;
|
|
49
|
+
if (!fenceAt[i] && /^## /.test(line)) {
|
|
50
|
+
const base = line.trimEnd();
|
|
51
|
+
const n = (seen.get(base) ?? 0) + 1;
|
|
52
|
+
seen.set(base, n);
|
|
53
|
+
// suspect: heading-shaped line after an unclosed fence opener — possibly inside the
|
|
54
|
+
// owner's intended code block, so the merge never rewrites or removes it.
|
|
55
|
+
sections.push({ key: n === 1 ? base : `${base}#${n}`, raw: '', suspect: fenceAt.unclosedFrom !== undefined && i > fenceAt.unclosedFrom });
|
|
56
|
+
}
|
|
57
|
+
sections[sections.length - 1].raw += text;
|
|
58
|
+
});
|
|
59
|
+
return sections;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export function sectionHashes(text, { markdown = true } = {}) {
|
|
63
|
+
sectioned = markdown;
|
|
64
|
+
const out = {};
|
|
65
|
+
for (const s of parseSections(normalizeEol(text.replace(/^/, '')))) out[s.key] = hashOf(s.raw);
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
const trailingWs = (raw) => raw.slice(raw.trimEnd().length);
|
|
70
|
+
|
|
71
|
+
export function mergeManagedTemplate({ existing, template, recorded = null, markdown = true }) {
|
|
72
|
+
sectioned = markdown;
|
|
73
|
+
const bom = existing.startsWith('');
|
|
74
|
+
const eol = existing.includes('\r\n') ? '\r\n' : '\n';
|
|
75
|
+
const existingLf = normalizeEol(existing.replace(/^/, ''));
|
|
76
|
+
const templateSections = parseSections(normalizeEol(template.replace(/^/, '')));
|
|
77
|
+
const tplByKey = new Map(templateSections.map((s) => [s.key, s]));
|
|
78
|
+
const sections = Object.fromEntries(templateSections.map((s) => [s.key, hashOf(s.raw)]));
|
|
79
|
+
const notices = [];
|
|
80
|
+
|
|
81
|
+
const parts = [];
|
|
82
|
+
const existingSections = parseSections(existingLf);
|
|
83
|
+
let removedTail = null;
|
|
84
|
+
for (const [idx, e] of existingSections.entries()) {
|
|
85
|
+
const t = tplByKey.get(e.key);
|
|
86
|
+
const base = recorded?.[e.key];
|
|
87
|
+
if (e.suspect) {
|
|
88
|
+
parts.push({ key: e.key, raw: e.raw });
|
|
89
|
+
} else if (t) {
|
|
90
|
+
const eh = hashOf(e.raw);
|
|
91
|
+
const th = sections[e.key];
|
|
92
|
+
if (eh === th) {
|
|
93
|
+
parts.push({ key: e.key, raw: e.raw });
|
|
94
|
+
} else if (typeof base === 'string' && eh === base) {
|
|
95
|
+
parts.push({ key: e.key, raw: t.raw.trimEnd() + trailingWs(e.raw) });
|
|
96
|
+
} else {
|
|
97
|
+
// Owner-changed (or no baseline): keep. Notice only when the template moved since the record.
|
|
98
|
+
if (typeof base === 'string' && th !== base) notices.push({ heading: e.key || '(preamble)' });
|
|
99
|
+
parts.push({ key: e.key, raw: e.raw });
|
|
100
|
+
}
|
|
101
|
+
} else if (typeof base === 'string' && hashOf(e.raw) === base) {
|
|
102
|
+
// Upstream removed it and the owner never changed it.
|
|
103
|
+
if (idx === existingSections.length - 1) removedTail = trailingWs(e.raw);
|
|
104
|
+
} else {
|
|
105
|
+
parts.push({ key: e.key, raw: e.raw });
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
if (removedTail !== null && parts.length > 0) {
|
|
110
|
+
const last = parts[parts.length - 1];
|
|
111
|
+
last.raw = last.raw.trimEnd() + removedTail;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
const have = new Set(parts.map((p) => p.key));
|
|
115
|
+
// Idempotence guard: a template section whose exact heading line already appears as ANY line
|
|
116
|
+
// of the existing text (fenced or not) is never appended again. Fence pairing in an
|
|
117
|
+
// owner-edited file is ambiguous: an owner's unclosed opener pairs with the first fence of a
|
|
118
|
+
// template-added section's own code block, shifting every later pairing, so headings that sit
|
|
119
|
+
// "inside closed fences" cannot be trusted to be quoted text. Fenced lines must therefore
|
|
120
|
+
// count, otherwise the file grows on every run. Limit: a heading the owner merely quoted in a
|
|
121
|
+
// code block blocks the real template section of that name.
|
|
122
|
+
const existingLines = new Set(existingLf.split('\n').map((l) => l.trimEnd()));
|
|
123
|
+
templateSections.forEach((t, i) => {
|
|
124
|
+
if (have.has(t.key)) return;
|
|
125
|
+
if (t.key !== '' && existingLines.has(t.key.replace(/#\d+$/, ''))) return;
|
|
126
|
+
let at = parts.length;
|
|
127
|
+
for (let j = i - 1; j >= 0; j -= 1) {
|
|
128
|
+
const idx = parts.findIndex((p) => p.key === templateSections[j].key);
|
|
129
|
+
if (idx !== -1) { at = idx + 1; break; }
|
|
130
|
+
}
|
|
131
|
+
parts.splice(at, 0, { key: t.key, raw: t.raw, added: true });
|
|
132
|
+
have.add(t.key);
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
parts.forEach((p, i) => {
|
|
136
|
+
if (!p.added) return;
|
|
137
|
+
if (i < parts.length - 1 && !p.raw.endsWith('\n\n')) p.raw = `${p.raw.trimEnd()}\n\n`;
|
|
138
|
+
const prev = parts[i - 1];
|
|
139
|
+
if (prev && prev.raw !== '' && !prev.raw.endsWith('\n\n')) prev.raw = `${prev.raw.trimEnd()}\n\n`;
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
const mergedLf = parts.map((p) => p.raw).join('');
|
|
143
|
+
if (mergedLf === existingLf) return { content: existing, changed: false, notices, sections };
|
|
144
|
+
const body = eol === '\r\n' ? mergedLf.replace(/\n/g, '\r\n') : mergedLf;
|
|
145
|
+
return { content: (bom ? '' : '') + body, changed: true, notices, sections };
|
|
146
|
+
}
|