fix(release): version AUR asset cache aliases

backlog/tasks/task-166 - Prevent-AUR-upgrade-cache-collisions-for-unversioned-release-assets.md

@@ -0,0 +1,73 @@
+---
+id: TASK-166
+title: Prevent AUR upgrade cache collisions for unversioned release assets
+status: Done
+assignee:
+  - Codex
+created_date: '2026-03-17 18:10'
+updated_date: '2026-03-17 18:14'
+labels:
+  - release
+  - packaging
+  - linux
+dependencies:
+  - TASK-165
+references:
+  - /home/sudacode/projects/japanese/SubMiner/.github/workflows/release.yml
+  - /home/sudacode/projects/japanese/SubMiner/scripts/update-aur-package.sh
+  - /home/sudacode/projects/japanese/SubMiner/scripts/update-aur-package.test.ts
+  - /home/sudacode/projects/japanese/SubMiner/packaging/aur/subminer-bin/PKGBUILD
+  - /home/sudacode/projects/japanese/SubMiner/packaging/aur/subminer-bin/.SRCINFO
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Fix the AUR release metadata generated by the tagged-release workflow so end-user upgrades do not reuse stale cached downloads for unversioned `subminer` and `subminer-assets.tar.gz` source names.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 AUR packaging generated for a new `pkgver` uses versioned local source aliases for the non-versioned GitHub release assets.
+- [x] #2 The package install step references the versioned local launcher filename correctly.
+- [x] #3 Regression coverage fails if metadata generation reintroduces stable cache-colliding source aliases.
+- [x] #4 Targeted verification records the commands run and results.
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Add a failing regression test around `scripts/update-aur-package.sh` output for versioned local source aliases.
+2. Update the repo AUR template and `.SRCINFO` rewrite logic to stamp versioned alias names for `subminer` and `subminer-assets`.
+3. Verify the generated metadata and targeted workflow/package tests, then record results here.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Root cause: the AUR package used stable local source aliases for the unversioned `subminer` and `subminer-assets.tar.gz` GitHub release assets. `makepkg`/AUR helpers can reuse those cached filenames across upgrades, so a stale cached download survives into a newer `pkgver` and then fails checksum validation.
+
+Patched the repo AUR template to version the local cache aliases:
+- `subminer-${pkgver}::.../subminer`
+- `subminer-assets-${pkgver}.tar.gz::.../subminer-assets.tar.gz`
+
+Updated `package()` to install the versioned local wrapper filename, and updated `scripts/update-aur-package.sh` so the generated `.SRCINFO` stamps matching concrete versioned aliases for release automation.
+
+Added regression assertions in `scripts/update-aur-package.test.ts` covering both versioned source aliases and the launcher install path, then watched that test fail before the patch and pass after it.
+
+Verification:
+- `bun test scripts/update-aur-package.test.ts`
+- `bash -n scripts/update-aur-package.sh && bash -n packaging/aur/subminer-bin/PKGBUILD`
+- `bun run typecheck`
+- `bun run test:fast`
+- `bun run test:env`
+- `bun run build`
+- `bun run test:smoke:dist`
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+The tagged-release AUR metadata path now emits versioned local source aliases for the non-versioned GitHub release assets, preventing stale `makepkg` cache reuse across `subminer-bin` upgrades. The change is covered by a regression test and passed the repo's maintained verification gate.
+<!-- SECTION:FINAL_SUMMARY:END -->

changes/jlpt-duplicate-log-summary.md

@@ -0,0 +1,4 @@
+type: fixed
+area: jlpt
+
+- Reduced JLPT dictionary startup log noise by summarizing duplicate surface-form collisions instead of logging one line per duplicate entry.

packaging/aur/subminer-bin/.SRCINFO

@@ -27,8 +27,8 @@ pkgbase = subminer-bin
 	options = !strip
 	options = !debug
 	source = SubMiner-0.6.2.AppImage::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/SubMiner-0.6.2.AppImage
-	source = subminer::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/subminer
-	source = subminer-assets.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/subminer-assets.tar.gz
+	source = subminer-0.6.2::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/subminer
+	source = subminer-assets-0.6.2.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v0.6.2/subminer-assets.tar.gz
 	sha256sums = c91667adbbc47a0fba34855358233454a9ea442ab57510546b2219abd1f2461e
 	sha256sums = 85050918e14cb2512fcd34be83387a2383fa5c206dc1bdc11e8d98f7d37817e5
 	sha256sums = 210113be64a06840f4dfaebc22a8e6fc802392f1308413aa00d9348c804ab2a1

packaging/aur/subminer-bin/PKGBUILD

@@ -32,8 +32,8 @@ provides=("subminer=${pkgver}")
 conflicts=('subminer')
 source=(
 	"SubMiner-${pkgver}.AppImage::https://github.com/ksyasuda/SubMiner/releases/download/v${pkgver}/SubMiner-${pkgver}.AppImage"
-	"subminer::https://github.com/ksyasuda/SubMiner/releases/download/v${pkgver}/subminer"
-	"subminer-assets.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v${pkgver}/subminer-assets.tar.gz"
+	"subminer-${pkgver}::https://github.com/ksyasuda/SubMiner/releases/download/v${pkgver}/subminer"
+	"subminer-assets-${pkgver}.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v${pkgver}/subminer-assets.tar.gz"
 )
 sha256sums=(
 	'c91667adbbc47a0fba34855358233454a9ea442ab57510546b2219abd1f2461e'
@@ -50,7 +50,7 @@ package() {
 	install -dm755 "${pkgdir}/opt/SubMiner"
 	ln -s '/opt/SubMiner/SubMiner.AppImage' "${pkgdir}/usr/bin/SubMiner.AppImage"
 
-	install -Dm755 "${srcdir}/subminer" "${pkgdir}/usr/bin/subminer"
+	install -Dm755 "${srcdir}/subminer-${pkgver}" "${pkgdir}/usr/bin/subminer"
 
 	install -Dm644 "${srcdir}/config.example.jsonc" \
 		"${pkgdir}/usr/share/SubMiner/config.example.jsonc"

scripts/update-aur-package.sh

@@ -160,13 +160,13 @@ awk \
     found_source_appimage = 1
     next
   }
-  /^\tsource = subminer::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v.*\/subminer$/ {
-    print "\tsource = subminer::https://github.com/ksyasuda/SubMiner/releases/download/v" version "/subminer"
+  /^\tsource = subminer-.*::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v.*\/subminer$/ {
+    print "\tsource = subminer-" version "::https://github.com/ksyasuda/SubMiner/releases/download/v" version "/subminer"
     found_source_wrapper = 1
     next
   }
-  /^\tsource = subminer-assets\.tar\.gz::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v.*\/subminer-assets\.tar\.gz$/ {
-    print "\tsource = subminer-assets.tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v" version "/subminer-assets.tar.gz"
+  /^\tsource = subminer-assets-.*\.tar\.gz::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v.*\/subminer-assets\.tar\.gz$/ {
+    print "\tsource = subminer-assets-" version ".tar.gz::https://github.com/ksyasuda/SubMiner/releases/download/v" version "/subminer-assets.tar.gz"
     found_source_assets = 1
     next
   }

scripts/update-aur-package.test.ts

@@ -52,12 +52,32 @@ test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
     );
 
     assert.match(pkgbuild, /^pkgver=0\.6\.3$/m);
+    assert.match(
+      pkgbuild,
+      /^\s*"subminer-\$\{pkgver\}::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v\$\{pkgver\}\/subminer"$/m,
+    );
+    assert.match(
+      pkgbuild,
+      /^\s*"subminer-assets-\$\{pkgver\}\.tar\.gz::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v\$\{pkgver\}\/subminer-assets\.tar\.gz"$/m,
+    );
+    assert.match(
+      pkgbuild,
+      /^\s*install -Dm755 "\$\{srcdir\}\/subminer-\$\{pkgver\}" "\$\{pkgdir\}\/usr\/bin\/subminer"$/m,
+    );
     assert.match(srcinfo, /^\tpkgver = 0\.6\.3$/m);
     assert.match(srcinfo, /^\tprovides = subminer=0\.6\.3$/m);
     assert.match(
       srcinfo,
       /^\tsource = SubMiner-0\.6\.3\.AppImage::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v0\.6\.3\/SubMiner-0\.6\.3\.AppImage$/m,
     );
+    assert.match(
+      srcinfo,
+      /^\tsource = subminer-0\.6\.3::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v0\.6\.3\/subminer$/m,
+    );
+    assert.match(
+      srcinfo,
+      /^\tsource = subminer-assets-0\.6\.3\.tar\.gz::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v0\.6\.3\/subminer-assets\.tar\.gz$/m,
+    );
     assert.match(srcinfo, new RegExp(`^\\tsha256sums = ${expectedSums[0]}$`, 'm'));
     assert.match(srcinfo, new RegExp(`^\\tsha256sums = ${expectedSums[1]}$`, 'm'));
     assert.match(srcinfo, new RegExp(`^\\tsha256sums = ${expectedSums[2]}$`, 'm'));

src/core/services/jlpt-vocab.test.ts

@@ -6,9 +6,16 @@ import test from 'node:test';
 
 import { createJlptVocabularyLookup } from './jlpt-vocab';
 
-test('createJlptVocabularyLookup loads JLPT bank entries and resolves known levels', async () => {
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jlpt-dict-'));
+}
+
+test('createJlptVocabularyLookup loads JLPT bank entries and resolves known levels', async (t) => {
   const logs: string[] = [];
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jlpt-dict-'));
+  const tempDir = createTempDir();
+  t.after(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
   fs.writeFileSync(
     path.join(tempDir, 'term_meta_bank_5.json'),
     JSON.stringify([
@@ -37,8 +44,11 @@ test('createJlptVocabularyLookup loads JLPT bank entries and resolves known leve
   );
 });
 
-test('createJlptVocabularyLookup does not require synchronous fs APIs', async () => {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jlpt-dict-'));
+test('createJlptVocabularyLookup does not require synchronous fs APIs', async (t) => {
+  const tempDir = createTempDir();
+  t.after(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
   fs.writeFileSync(
     path.join(tempDir, 'term_meta_bank_4.json'),
     JSON.stringify([['見る', 1, { frequency: { displayValue: 3 } }]]),
@@ -73,3 +83,47 @@ test('createJlptVocabularyLookup does not require synchronous fs APIs', async ()
     (fs as unknown as Record<string, unknown>).existsSync = existsSync;
   }
 });
+
+test('createJlptVocabularyLookup summarizes duplicate JLPT terms without per-entry log spam', async (t) => {
+  const logs: string[] = [];
+  const tempDir = createTempDir();
+  t.after(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+  fs.writeFileSync(
+    path.join(tempDir, 'term_meta_bank_1.json'),
+    JSON.stringify([
+      ['余り', 1, { frequency: { displayValue: 'N1' }, reading: 'あんまり' }],
+      ['私', 2, { frequency: { displayValue: 'N1' }, reading: 'あたし' }],
+    ]),
+  );
+  fs.writeFileSync(path.join(tempDir, 'term_meta_bank_2.json'), JSON.stringify([]));
+  fs.writeFileSync(path.join(tempDir, 'term_meta_bank_3.json'), JSON.stringify([]));
+  fs.writeFileSync(path.join(tempDir, 'term_meta_bank_4.json'), JSON.stringify([]));
+  fs.writeFileSync(
+    path.join(tempDir, 'term_meta_bank_5.json'),
+    JSON.stringify([
+      ['余り', 3, { frequency: { displayValue: 'N5' }, reading: 'あまり' }],
+      ['私', 4, { frequency: { displayValue: 'N5' }, reading: 'わたし' }],
+      ['私', 5, { frequency: { displayValue: 'N5' }, reading: 'わたくし' }],
+    ]),
+  );
+
+  const lookup = await createJlptVocabularyLookup({
+    searchPaths: [tempDir],
+    log: (message) => {
+      logs.push(message);
+    },
+  });
+
+  assert.equal(lookup('余り'), 'N1');
+  assert.equal(lookup('私'), 'N1');
+  assert.equal(
+    logs.some((entry) => entry.includes('keeping') && entry.includes('instead')),
+    false,
+  );
+  assert.equal(
+    logs.some((entry) => entry.includes('collapsed') && entry.includes('duplicate')),
+    true,
+  );
+});

src/core/services/jlpt-vocab.ts

@@ -22,10 +22,17 @@ const JLPT_LEVEL_PRECEDENCE: Record<JlptLevel, number> = {
   N4: 2,
   N5: 1,
 };
+const JLPT_DUPLICATE_LOG_EXAMPLE_LIMIT = 5;
 
 const NOOP_LOOKUP = (): null => null;
 const ENTRY_YIELD_INTERVAL = 5000;
 
+interface JlptDuplicateStats {
+  duplicateEntryCount: number;
+  duplicateTerms: Set<string>;
+  exampleTerms: string[];
+}
+
 function isErrorCode(error: unknown, code: string): boolean {
   return Boolean(error && typeof error === 'object' && (error as { code?: unknown }).code === code);
 }
@@ -47,11 +54,30 @@ function hasFrequencyDisplayValue(meta: unknown): boolean {
   return Object.prototype.hasOwnProperty.call(frequency as Record<string, unknown>, 'displayValue');
 }
 
+function createJlptDuplicateStats(): JlptDuplicateStats {
+  return {
+    duplicateEntryCount: 0,
+    duplicateTerms: new Set<string>(),
+    exampleTerms: [],
+  };
+}
+
+function recordJlptDuplicate(stats: JlptDuplicateStats, term: string): void {
+  stats.duplicateEntryCount += 1;
+  stats.duplicateTerms.add(term);
+  if (
+    stats.exampleTerms.length < JLPT_DUPLICATE_LOG_EXAMPLE_LIMIT &&
+    !stats.exampleTerms.includes(term)
+  ) {
+    stats.exampleTerms.push(term);
+  }
+}
+
 async function addEntriesToMap(
   rawEntries: unknown,
   level: JlptLevel,
   terms: Map<string, JlptLevel>,
-  log: (message: string) => void,
+  duplicateStats: JlptDuplicateStats,
 ): Promise<void> {
   const shouldUpdateLevel = (
     existingLevel: JlptLevel | undefined,
@@ -90,14 +116,13 @@ async function addEntriesToMap(
     }
 
     const existingLevel = terms.get(normalizedTerm);
-    if (shouldUpdateLevel(existingLevel, level)) {
-      terms.set(normalizedTerm, level);
-      continue;
+    if (existingLevel !== undefined) {
+      recordJlptDuplicate(duplicateStats, normalizedTerm);
     }
 
-    log(
-      `JLPT dictionary already has ${normalizedTerm} as ${existingLevel}; keeping that level instead of ${level}`,
-    );
+    if (shouldUpdateLevel(existingLevel, level)) {
+      terms.set(normalizedTerm, level);
+    }
   }
 }
 
@@ -106,6 +131,7 @@ async function collectDictionaryFromPath(
   log: (message: string) => void,
 ): Promise<Map<string, JlptLevel>> {
   const terms = new Map<string, JlptLevel>();
+  const duplicateStats = createJlptDuplicateStats();
 
   for (const bank of JLPT_BANK_FILES) {
     const bankPath = path.join(dictionaryPath, bank.filename);
@@ -146,12 +172,22 @@ async function collectDictionaryFromPath(
     }
 
     const beforeSize = terms.size;
-    await addEntriesToMap(rawEntries, bank.level, terms, log);
+    await addEntriesToMap(rawEntries, bank.level, terms, duplicateStats);
     if (terms.size === beforeSize) {
       log(`JLPT bank file contained no extractable entries: ${bankPath}`);
     }
   }
 
+  if (duplicateStats.duplicateEntryCount > 0) {
+    const examples =
+      duplicateStats.exampleTerms.length > 0
+        ? `; examples: ${duplicateStats.exampleTerms.join(', ')}`
+        : '';
+    log(
+      `JLPT dictionary collapsed ${duplicateStats.duplicateEntryCount} duplicate JLPT entries across ${duplicateStats.duplicateTerms.size} terms; keeping highest-precedence level per surface form${examples}`,
+    );
+  }
+
   return terms;
 }