feat: Add POS information to tag generation API across C, C++, and JS layers

Extend the tag generation API so each tag carries its part-of-speech
alongside the tag text, enabling callers to filter or display tags by POS
without re-analyzing the text.

C++ API changes:
- Introduce TagEntry struct in tag_generator.h with tag (std::string) and
  pos (core::PartOfSpeech) fields
- TagGenerator::generate() and generateFromText() now return
  std::vector<TagEntry> instead of std::vector<std::string>
- Suzume::generateTags() overloads updated accordingly in suzume.h/cpp

C API changes (suzume_c.h/cpp):
- Add const char** pos field to suzume_tags_t struct alongside existing
  char** tags and size_t count fields
- suzume_generate_tags() and suzume_generate_tags_with_options() populate
  pos array using posToString() on each TagEntry
- suzume_tags_free() correctly frees the pos array to avoid memory leaks

JS/WASM API changes (js/index.ts):
- Introduce Tag interface with tag: string and pos: string fields
- generateTags() return type changed from string[] to Tag[]
- parseTags() reads the new pos pointer array from suzume_tags_t layout
  (field order: tags ptr, pos ptr, count)
- Fix memory access: use HEAPU32-derived Uint8Array instead of HEAPU8
  (not exported by Emscripten) for struct writes in loadBinaryDictionary
  and option struct initialization

CLI output:
- suzume-cli and cmd_analyze now output tag + tab + POS on each line
- cmd_test.cpp adapted to extract tag.tag for comparison set

WASM test suite refactored:
- Remove monolithic suzume.test.ts
- Add helpers.ts: shared WASM module loader, allocString, parseMorphemes,
  parseTags, getTagCount utilities
- Add c-api-analyze.test.ts: C API analyze tests covering POS fields,
  conj fields, mixed POS sentences, and create_with_options
- Add c-api-tags.test.ts: C API tag generation tests covering POS filter,
  max_tags, min_length, and excludeBasic options
- Add js-api.test.ts: JS API struct layout compatibility tests

C++ unit tests (tag_generator_test.cpp):
- Update all tag comparisons from tag == "str" to tag.tag == "str"
- Add POS assertions where appropriate (Verb, Adjective, Adverb, Particle,
  Auxiliary, Noun, Pronoun)

Author: libraz

js/index.ts

@@ -57,6 +57,16 @@ export interface Morpheme {
   conjForm: string | null;
 }
 
+/**
+ * Tag entry with POS information
+ */
+export interface Tag {
+  /** Tag text (surface or lemma) */
+  tag: string;
+  /** Part of speech (English) */
+  pos: string;
+}
+
 /**
  * Options for tag generation
  */
@@ -246,9 +256,9 @@ export class Suzume {
    *
    * @param text - UTF-8 encoded Japanese text
    * @param options - Optional tag generation options
-   * @returns Array of tag strings
+   * @returns Array of tag entries with POS information
    */
-  generateTags(text: string, options?: TagOptions): string[] {
+  generateTags(text: string, options?: TagOptions): Tag[] {
     const textBytes = this.module.lengthBytesUTF8(text) + 1;
     const textPtr = this.module._malloc(textBytes);
 
@@ -275,13 +285,10 @@ export class Suzume {
         const optionsPtr = this.module._malloc(OPTIONS_SIZE);
 
         try {
-          const heap = (this.module as unknown as { HEAPU8: Uint8Array }).HEAPU8;
           const heapU32 = (this.module as unknown as { HEAPU32: Uint32Array }).HEAPU32;
 
-          // Zero out the struct first
-          heap.fill(0, optionsPtr, optionsPtr + OPTIONS_SIZE);
-
-          heap[optionsPtr] = posFilter;
+          // pos_filter is uint8_t at offset 0, padded to 4 bytes — write as uint32
+          heapU32[optionsPtr >> 2] = posFilter;
           heapU32[(optionsPtr + 4) >> 2] = options.excludeBasic ? 1 : 0;
           heapU32[(optionsPtr + 8) >> 2] = options.useLemma !== false ? 1 : 0;
           heapU32[(optionsPtr + 12) >> 2] = options.minLength ?? 2;
@@ -345,8 +352,10 @@ export class Suzume {
   loadBinaryDictionary(data: Uint8Array): boolean {
     const dataPtr = this.module._malloc(data.byteLength);
     try {
-      const heap = (this.module as unknown as { HEAPU8: Uint8Array }).HEAPU8;
-      heap.set(data, dataPtr);
+      // Derive Uint8Array view from HEAPU32's underlying buffer (HEAPU8 may not be exported)
+      const heapU32 = (this.module as unknown as { HEAPU32: Uint32Array }).HEAPU32;
+      const heapU8 = new Uint8Array(heapU32.buffer);
+      heapU8.set(data, dataPtr);
       return this._loadBinaryDict(this.handle, dataPtr, data.byteLength) === 1;
     } finally {
       this.module._free(dataPtr);
@@ -425,20 +434,26 @@ export class Suzume {
   }
 
   // Parse suzume_tags_t structure from WASM memory
-  private parseTags(tagsPtr: number): string[] {
-    // suzume_tags_t layout:
-    // - tags: pointer to char** (4 bytes on wasm32)
-    // - count: size_t (4 bytes on wasm32)
+  private parseTags(tagsPtr: number): Tag[] {
+    // suzume_tags_t layout (wasm32):
+    // - tags: pointer to char** (4 bytes)
+    // - pos: pointer to const char** (4 bytes)
+    // - count: size_t (4 bytes)
     const HEAPU32 = (this.module as unknown as { HEAPU32: Uint32Array }).HEAPU32;
 
     const tagsArrayPtr = HEAPU32[tagsPtr >> 2];
-    const count = HEAPU32[(tagsPtr >> 2) + 1];
+    const posArrayPtr = HEAPU32[(tagsPtr >> 2) + 1];
+    const count = HEAPU32[(tagsPtr >> 2) + 2];
 
-    const tags: string[] = [];
+    const tags: Tag[] = [];
 
     for (let idx = 0; idx < count; idx++) {
       const tagPtr = HEAPU32[(tagsArrayPtr >> 2) + idx];
-      tags.push(this.module.UTF8ToString(tagPtr));
+      const posPtr = HEAPU32[(posArrayPtr >> 2) + idx];
+      tags.push({
+        tag: this.module.UTF8ToString(tagPtr),
+        pos: this.module.UTF8ToString(posPtr),
+      });
     }
 
     return tags;

src/cli/main.cpp

@@ -97,7 +97,7 @@ int main(int argc, char* argv[]) {
     // Output tags
     auto tags = analyzer.generateTags(text);
     for (const auto& tag : tags) {
-      std::cout << tag << "\n";
+      std::cout << tag.tag << "\t" << suzume::core::posToString(tag.pos) << "\n";
     }
   } else {
     // Output morpheme analysis

src/postprocess/tag_generator.cpp

@@ -88,12 +88,12 @@ std::string TagGenerator::getTagString(const core::Morpheme& morpheme) const {
   return morpheme.surface;
 }
 
-std::vector<std::string> TagGenerator::generate(
+std::vector<TagEntry> TagGenerator::generate(
     const std::vector<core::Morpheme>& morphemes) const {
   // Post-process morphemes
   auto processed = postprocessor_.process(morphemes);
 
-  std::vector<std::string> tags;
+  std::vector<TagEntry> tags;
   std::unordered_set<std::string> seen;
 
   for (const auto& morpheme : processed) {
@@ -116,7 +116,7 @@ std::vector<std::string> TagGenerator::generate(
       seen.insert(tag);
     }
 
-    tags.push_back(tag);
+    tags.push_back({tag, morpheme.pos});
 
     // Check max tags
     if (options_.max_tags > 0 && tags.size() >= options_.max_tags) {
@@ -127,7 +127,7 @@ std::vector<std::string> TagGenerator::generate(
   return tags;
 }
 
-std::vector<std::string> TagGenerator::generateFromText(std::string_view /*text*/) {
+std::vector<TagEntry> TagGenerator::generateFromText(std::string_view /*text*/) {
   // This would require access to Analyzer
   // For now, return empty - caller should use Analyzer + generate()
   return {};

src/postprocess/tag_generator.h

@@ -36,6 +36,14 @@ struct TagGeneratorOptions {
   bool exclude_basic = false;        // Exclude basic words (hiragana-only lemma)
 };
 
+/**
+ * @brief Tag entry with POS information
+ */
+struct TagEntry {
+  std::string tag;
+  core::PartOfSpeech pos;
+};
+
 /**
  * @brief Tag generator from morphemes
  */
@@ -47,17 +55,17 @@ class TagGenerator {
   /**
    * @brief Generate tags from morphemes
    * @param morphemes Input morphemes
-   * @return Vector of tag strings
+   * @return Vector of tag entries with POS information
    */
-  std::vector<std::string> generate(
+  std::vector<TagEntry> generate(
       const std::vector<core::Morpheme>& morphemes) const;
 
   /**
    * @brief Generate tags from text using analyzer
    * @param text Input text
-   * @return Vector of tag strings
+   * @return Vector of tag entries with POS information
    */
-  static std::vector<std::string> generateFromText(std::string_view text);
+  static std::vector<TagEntry> generateFromText(std::string_view text);
 
  private:
   TagGeneratorOptions options_;

src/suzume-cli/cmd_analyze.cpp

@@ -39,9 +39,9 @@ void outputMorpheme(const std::vector<core::Morpheme>& morphemes) {
   }
 }
 
-void outputTags(const std::vector<std::string>& tags) {
+void outputTags(const std::vector<postprocess::TagEntry>& tags) {
   for (const auto& tag : tags) {
-    std::cout << tag << "\n";
+    std::cout << tag.tag << "\t" << core::posToString(tag.pos) << "\n";
   }
 }
 

src/suzume-cli/cmd_test.cpp

@@ -34,7 +34,10 @@ std::vector<std::string> split(const std::string& str, char delim) {
 bool runSingleTest(Suzume& analyzer, const std::string& input,
                    const std::set<std::string>& expected, bool verbose) {
   auto tags = analyzer.generateTags(input);
-  std::set<std::string> actual(tags.begin(), tags.end());
+  std::set<std::string> actual;
+  for (const auto& t : tags) {
+    actual.insert(t.tag);
+  }
 
   bool passed = (actual == expected);
 

src/suzume.cpp

@@ -179,12 +179,12 @@ std::vector<core::Morpheme> Suzume::analyzeDebug(std::string_view text,
   return impl_->postprocessor.process(morphemes);
 }
 
-std::vector<std::string> Suzume::generateTags(std::string_view text) const {
+std::vector<postprocess::TagEntry> Suzume::generateTags(std::string_view text) const {
   auto morphemes = impl_->analyzer.analyze(text);
   return impl_->tag_generator.generate(morphemes);
 }
 
-std::vector<std::string> Suzume::generateTags(
+std::vector<postprocess::TagEntry> Suzume::generateTags(
     std::string_view text,
     const postprocess::TagGeneratorOptions& options) const {
   auto morphemes = impl_->analyzer.analyze(text);

src/suzume.h

@@ -100,17 +100,17 @@ class Suzume {
   /**
    * @brief Generate tags from text
    * @param text UTF-8 encoded Japanese text
-   * @return Vector of tag strings
+   * @return Vector of tag entries with POS information
    */
-  std::vector<std::string> generateTags(std::string_view text) const;
+  std::vector<postprocess::TagEntry> generateTags(std::string_view text) const;
 
   /**
    * @brief Generate tags from text with custom options
    * @param text UTF-8 encoded Japanese text
    * @param options Tag generation options (POS filter, exclude_basic, etc.)
-   * @return Vector of tag strings
+   * @return Vector of tag entries with POS information
    */
-  std::vector<std::string> generateTags(
+  std::vector<postprocess::TagEntry> generateTags(
       std::string_view text,
       const postprocess::TagGeneratorOptions& options) const;
 

src/suzume_c.cpp

@@ -168,14 +168,22 @@ SUZUME_EXPORT suzume_tags_t* suzume_generate_tags(suzume_t handle,
 
     if (result->count == 0) {
       result->tags = nullptr;
+      result->pos = nullptr;
       return result;
     }
 
     result->tags = new char*[result->count];
+    result->pos = new const char*[result->count];
 
     for (size_t idx = 0; idx < result->count; ++idx) {
-      result->tags[idx] = new char[tags[idx].size() + 1];
-      std::strcpy(result->tags[idx], tags[idx].c_str());
+      result->tags[idx] = new char[tags[idx].tag.size() + 1];
+      std::strcpy(result->tags[idx], tags[idx].tag.c_str());
+
+      auto pos_str = suzume::core::posToString(tags[idx].pos);
+      auto* pos_copy = new char[pos_str.size() + 1];
+      std::memcpy(pos_copy, pos_str.data(), pos_str.size());
+      pos_copy[pos_str.size()] = '\0';
+      result->pos[idx] = pos_copy;
     }
 
     return result;
@@ -205,14 +213,22 @@ SUZUME_EXPORT suzume_tags_t* suzume_generate_tags_with_options(
 
     if (result->count == 0) {
       result->tags = nullptr;
+      result->pos = nullptr;
       return result;
     }
 
     result->tags = new char*[result->count];
+    result->pos = new const char*[result->count];
 
     for (size_t idx = 0; idx < result->count; ++idx) {
-      result->tags[idx] = new char[tags[idx].size() + 1];
-      std::strcpy(result->tags[idx], tags[idx].c_str());
+      result->tags[idx] = new char[tags[idx].tag.size() + 1];
+      std::strcpy(result->tags[idx], tags[idx].tag.c_str());
+
+      auto pos_str = suzume::core::posToString(tags[idx].pos);
+      auto* pos_copy = new char[pos_str.size() + 1];
+      std::memcpy(pos_copy, pos_str.data(), pos_str.size());
+      pos_copy[pos_str.size()] = '\0';
+      result->pos[idx] = pos_copy;
     }
 
     return result;
@@ -233,6 +249,14 @@ SUZUME_EXPORT void suzume_tags_free(suzume_tags_t* tags) {
     delete[] tags->tags;
   }
 
+  if (tags->pos != nullptr) {
+    for (size_t idx = 0; idx < tags->count; ++idx) {
+      // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
+      delete[] const_cast<char*>(tags->pos[idx]);
+    }
+    delete[] tags->pos;
+  }
+
   delete tags;
 }
 

src/suzume_c.h

@@ -52,8 +52,9 @@ typedef struct {
  * @brief Tag generation result structure
  */
 typedef struct {
-  char** tags;   /**< Array of tag strings */
-  size_t count;  /**< Number of tags */
+  char** tags;       /**< Array of tag strings */
+  const char** pos;  /**< Array of POS strings (English, e.g. "NOUN", "VERB") */
+  size_t count;      /**< Number of tags */
 } suzume_tags_t;
 
 /**