@qnroa/qtype 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -13,6 +13,70 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.0.7] — 2026-08-26
+
+Fully backward compatible: existing repos parse unchanged. The
+new capability is opt-in — write card-level frontmatter only where
+a card differs from the material default.
+
+### Added
+- **`Card` runtime shape gains `type` and `tags` fields.** Populated
+  either by card-level frontmatter or by inheriting the material
+  default. Downstream code should read `card.type` / `card.tags`
+  instead of `material.meta.type` / `material.meta.tags` when it
+  wants per-card resolution.
+- **Card-level frontmatter.** After an H1 you may open a second
+  `---\n...\n---` YAML block declaring `type` and `tags` for that one
+  card. This lets a single file mix qa / code / article — e.g. one qa
+  "principle" card followed by four code cards for cpp / py / go / java.
+- **Material-level fields are defaults.** `material.type` is the
+  fallback type for cards that don't declare their own.
+  `material.tags` is unioned with each card's tags (deduped). A card
+  can always override with its own card-level fm.
+- **`publish build` emits a flat card pool.** `dist/material/index.json`
+  carries `cards`, `tagIndex`, and `typeIndex` alongside the existing
+  `materials` list so the reader can filter/pick without fetching
+  every `.md`.
+- **Migration scripts.** `scripts/migrate_card_fm.py` pushes
+  material-level defaults down into every card (opt-in). Bundled but
+  usually unnecessary — the parser now handles legacy files natively.
+
+### Changed
+- QTYPE.md rules updated: "one material one type" is gone; the new
+  spec is "material-level fields set defaults; cards can override".
+- Search / lint / all internal consumers operate on `card.type` and
+  `card.tags` directly (still transparently backed by material defaults
+  when the card doesn't override).
+
+## [0.0.6] - 2026-08-24
+
+### Changed
+
+- **`QTYPE.md` template documents nested `material/` folders as
+  first-class.** The template already-existing `walkMaterial` recurses
+  into `material/<category>/<slug>.md`, and `publish build` even uses
+  the first path segment as a fallback `type` when frontmatter omits
+  it — but the previous wording ("flat `material/` + `assets/` only",
+  rule #9) read as a ban on subdirectories, misleading Agent-driven
+  authors into flattening large repos. The template now:
+  - shows both flat and nested placements in the Directory Layout
+    tree, with a one-line note that both are supported and discovery
+    is recursive;
+  - adds a **Grouping by folder (optional)** section covering the
+    recursive-discovery behavior and the first-segment-as-fallback-`type`
+    shortcut (`material/code/hello.md` → `type: code` when frontmatter
+    is silent);
+  - reworks the Naming section to say each path segment (`<slug>`,
+    `<category>`) uses the same kebab-case rules;
+  - rewrites rule #9 to enumerate the allowed root-level directories
+    (`material/`, `material/assets/`, `raw/`) and cross-reference the
+    new subfolder section, replacing the misleading "flat only"
+    phrasing.
+  Applies to both `templates/en/QTYPE.md` and `templates/zh/QTYPE.md`.
+  No runtime code changed; existing repos are unaffected until they
+  regenerate their `QTYPE.md` via `qtype repo new` or copy the new
+  template in.
+
 ## [0.0.5] - 2026-08-22
 
 ### Fixed

package/CHANGELOG.zh.md

@@ -12,6 +12,56 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.0.7] — 2026-08-26
+
+完全向后兼容:老仓库解析不变。新能力是可选的 —— 只在卡片和材料
+默认不同时才写卡级 frontmatter。
+
+### 新增
+- **`Card` 运行时结构新增 `type` 和 `tags` 字段**。值来自卡级 fm
+  或从材料默认继承。下游代码在需要 per-card 语义时应读 `card.type` /
+  `card.tags`,不要读 `material.meta.type` / `material.meta.tags`。
+- **卡级 frontmatter**。H1 后可以开第二段 `---\n...\n---` YAML 声明
+  该卡的 `type` 和 `tags`。这样一个文件里可以自由混合 qa / code /
+  article —— 比如 1 张 qa 原理卡加 4 张不同语言的 code 实现卡。
+- **素材级字段变成默认值**。`material.type` 是卡的 fallback,卡不写
+  就继承。`material.tags` 和卡级 tags 合并去重。任何一张卡都能靠自己
+  的卡级 fm 覆盖默认。
+- **`publish build` 输出扁平卡池**。`dist/material/index.json` 新增
+  `cards`、`tagIndex`、`typeIndex` 三个字段,reader 无需拉每份 md
+  就能做筛选。
+- **迁移脚本**:`scripts/migrate_card_fm.py` 一键把素材级 type/tags
+  下推到每张卡(可选,通常不需要 —— parser 原生支持向后继承)。
+
+### 变更
+- QTYPE.md 规则更新:"一个 material 一个 type" 改为"素材级字段是默认
+  值,卡可以覆盖"。
+- 搜索、lint、所有内部消费方直接读 `card.type` 加 `card.tags`(值来
+  自卡自身或素材默认,parser 透明处理)。
+
+## [0.0.6] - 2026-08-24
+
+### 变更
+
+- **`QTYPE.md` 模板把嵌套 `material/` 子目录写成一等公民**。
+  `walkMaterial` 一直就是递归的,`publish build` 甚至会用首段路径
+  作为 frontmatter 没写 `type` 时的 fallback —— 但之前模板里
+  "flat `material/` + `assets/` only"(规则 #9)的措辞读起来像禁止
+  子目录,把 Agent 驱动的作者误导成"再大的仓库也只能平铺"。这次:
+  - Directory Layout 目录树里同时画出平铺和嵌套两种放法,并加一行
+    "两种都支持,发现是递归的";
+  - 新增 **按分类分子目录(可选)** 小节,说明递归发现行为,以及
+    首段路径当 fallback `type` 的捷径(`material/code/hello.md`
+    在 frontmatter 没 `type` 时被视为 `type: code`);
+  - 命名节改为"每一段路径(`<slug>`、`<category>`)都用同一套
+    kebab-case 规则";
+  - 规则 #9 重写为枚举根目录允许的三个位置(`material/` /
+    `material/assets/` / `raw/`)并 xref 新的子目录小节,替换掉
+    误导性的"平铺"措辞。
+  同步改动 `templates/en/QTYPE.md` 和 `templates/zh/QTYPE.md`。
+  运行时代码没动;老仓库要拿到新文档需要重跑 `qtype repo new`
+  或手动把新模板拷进去。
+
 ## [0.0.5] - 2026-08-22
 
 ### 修复

package/dist/cli/commands/content/search/action.js

@@ -21,16 +21,16 @@ export async function contentSearchAction(query, opts = {}) {
         const rel = `${MATERIAL_DIR}/${file.rel}`;
         const src = readMaterial(file);
         const material = parseMaterial(src, rel);
-        const materialType = material.meta.type?.toLowerCase() ?? 'article';
-        if (typeFilter.length > 0 && !typeFilter.includes(materialType))
-            continue;
-        const materialTags = (material.meta.tags ?? []).map((t) => t.toLowerCase());
-        if (tagFilter.length > 0 &&
-            !tagFilter.every((wanted) => materialTags.includes(wanted))) {
-            continue;
-        }
         for (let i = 0; i < material.cards.length; i++) {
             const card = material.cards[i];
+            const cardType = card.type.toLowerCase();
+            if (typeFilter.length > 0 && !typeFilter.includes(cardType))
+                continue;
+            const cardTags = card.tags.map((t) => t.toLowerCase());
+            if (tagFilter.length > 0 &&
+                !tagFilter.every((wanted) => cardTags.includes(wanted))) {
+                continue;
+            }
             const question = card.question ?? card.title;
             const qLc = question.toLowerCase();
             const aLc = card.answer.toLowerCase();
@@ -50,8 +50,8 @@ export async function contentSearchAction(query, opts = {}) {
                 question,
                 answer: card.answer,
                 snippet,
-                type: material.meta.type,
-                tags: material.meta.tags ?? [],
+                type: card.type,
+                tags: card.tags,
             });
             if (hits.length >= limit)
                 break outer;

package/dist/cli/commands/content/validate/action.js

@@ -92,16 +92,14 @@ export async function contentValidateAction(opts = {}) {
                     questionIndex.set(key, here);
                 }
             }
-            // Card-level tag consistency was removed with the frontmatter
-            // simplification — only material-level tags exist now, handled below.
+            // Collect card tags for cross-corpus casing consistency check.
+            for (const tag of card.tags) {
+                const lower = tag.toLowerCase();
+                const set = tagVariants.get(lower) ?? new Set();
+                set.add(tag);
+                tagVariants.set(lower, set);
+            }
         });
-        // Material-level tag casing consistency.
-        for (const tag of material.meta.tags) {
-            const lower = tag.toLowerCase();
-            const set = tagVariants.get(lower) ?? new Set();
-            set.add(tag);
-            tagVariants.set(lower, set);
-        }
     }
     for (const [lower, variants] of tagVariants) {
         if (variants.size > 1) {

package/dist/cli/commands/publish/build/action.js

@@ -20,7 +20,7 @@ import { createRepoKv } from '../../../bootstrap.js';
 import { deriveAesKey, encryptString, DEFAULT_ARGON2_PARAMS, } from '../../../../core/encrypt.js';
 import { verifyPassword } from '../password/action.js';
 import { prerenderMermaid, emptyMermaidPass } from './mermaidPass.js';
-import { parseMaterialFrontmatter } from '../../../../core/parser/frontmatter.js';
+import { parseMaterial } from '../../../../core/parser/parseMaterial.js';
 import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 export async function publishBuildAction(opts = {}) {
     const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
@@ -51,11 +51,8 @@ export async function publishBuildAction(opts = {}) {
         const body = readMaterial(file);
         const filename = file.rel.split('/').pop() ?? file.rel;
         const title = readTitle(body) ?? filename.replace(/\.md$/, '');
-        const fm = parseMaterialFrontmatter(body).meta;
-        const fallbackType = file.rel.includes('/') ? file.rel.split('/')[0] : '';
-        const type = fm.type ?? fallbackType;
         const cardCount = countH1(body);
-        materials.push({ name: file.rel, body, title, type, tags: fm.tags, cardCount });
+        materials.push({ name: file.rel, body, title, cardCount });
     }
     // Mermaid pre-render — scan all bodies, produce svg + css maps.
     const mermaid = mermaidMode === 'prerender'
@@ -96,8 +93,6 @@ export async function publishBuildAction(opts = {}) {
         entries.push({
             file: m.name,
             title: m.title,
-            type: m.type,
-            tags: m.tags,
             cardCount: m.cardCount,
         });
     }
@@ -124,8 +119,52 @@ export async function publishBuildAction(opts = {}) {
     if (fs.existsSync(srcAssets)) {
         copyDir(srcAssets, path.join(targetMaterial, 'assets'));
     }
+    // Card-pool index — parse every material once so the view can
+    // filter across files by card-level type/tags without fetching each
+    // md. Cards keep their full effective (material + card fm merged)
+    // metadata; body content is NOT duplicated here (still fetched
+    // on-demand from the .md file).
+    const cardIndex = [];
+    const tagIndex = {};
+    const typeIndex = {};
+    for (const m of materials) {
+        let parsed;
+        try {
+            parsed = parseMaterial(m.body, m.name);
+        }
+        catch {
+            continue;
+        }
+        for (const card of parsed.cards) {
+            cardIndex.push({
+                id: card.id,
+                file: m.name,
+                title: card.title,
+                type: card.type,
+                tags: card.tags,
+            });
+            for (const tag of card.tags) {
+                if (!tagIndex[tag])
+                    tagIndex[tag] = [];
+                if (!tagIndex[tag].includes(m.name))
+                    tagIndex[tag].push(m.name);
+            }
+            const t = card.type || '';
+            if (t) {
+                if (!typeIndex[t])
+                    typeIndex[t] = [];
+                if (!typeIndex[t].includes(m.name))
+                    typeIndex[t].push(m.name);
+            }
+        }
+    }
     // Manifest: lists materials + optional encryption envelope + mermaid mode.
-    const manifest = { materials: entries };
+    const manifest = {
+        materials: entries,
+        cards: cardIndex,
+        tagIndex,
+        typeIndex,
+    };
     if (encryptCtx) {
         manifest.encrypted = {
             algo: 'AES-GCM',

package/dist/core/parser/frontmatter.js

@@ -15,7 +15,7 @@ const FM_RE = /^---\n([\s\S]*?)\n---\n?/;
  * per-type rules).
  */
 export function parseMaterialFrontmatter(source) {
-    const meta = { tags: [] };
+    const meta = {};
     const match = source.match(FM_RE);
     if (!match)
         return { meta, rest: source };
@@ -54,9 +54,32 @@ function parseTagList(value) {
         .filter(Boolean);
 }
 /**
- * Kept for backwards compatibility of the barrel export. Card-level
- * frontmatter is no longer used; this always returns empty meta and
- * the original block unchanged.
+ * Card-level frontmatter — sits on the very first non-empty lines of a
+ * card body (right after the H1). Same YAML-fence syntax as the
+ * material-level block so users don't have to learn a second grammar.
+ * Returns empty meta if the body doesn't start with `---`.
+ */
+export function parseCardFrontmatter(cardBody) {
+    const meta = { tags: [] };
+    const match = cardBody.match(FM_RE);
+    if (!match)
+        return { meta, rest: cardBody };
+    const body = match[1];
+    const fields = {};
+    for (const line of body.split('\n')) {
+        const kv = line.match(/^(\w+)\s*:\s*(.+)$/);
+        if (!kv)
+            continue;
+        fields[kv[1]] = kv[2].trim();
+    }
+    if (fields.type)
+        meta.type = fields.type;
+    if (fields.tags)
+        meta.tags = parseTagList(fields.tags);
+    return { meta, rest: cardBody.slice(match[0].length) };
+}
+/**
+ * Kept for backwards compatibility of the barrel export.
  */
 export function parseFrontmatter(block) {
     return { meta: { tags: [] }, rest: block };

package/dist/core/parser/parseMaterial.js

@@ -1,15 +1,16 @@
-import { parseMaterialFrontmatter } from './frontmatter.js';
+import { parseMaterialFrontmatter, parseCardFrontmatter } from './frontmatter.js';
 import { textToCharPlans } from '../keystroke/index.js';
 import { validateTypingText } from '../keystroke/textNormalize.js';
 import { containsCJK, romanize } from '../romanization/index.js';
 export function parseMaterial(source, filePath = 'inline') {
     const normalized = source.replace(/\r\n/g, '\n').trim() + '\n';
     const { meta: materialMeta, rest } = parseMaterialFrontmatter(normalized);
-    const materialType = materialMeta.type ?? 'article';
+    const defaultType = materialMeta.type;
+    const defaultTags = materialMeta.tags ?? [];
     const rawCards = splitByH1(rest);
     const cards = [];
     for (let i = 0; i < rawCards.length; i++) {
-        const card = parseCard(rawCards[i], materialType, filePath, i);
+        const card = parseCard(rawCards[i], defaultType, defaultTags, filePath, i);
         if (card)
             cards.push(attachRomanization(card));
     }
@@ -57,7 +58,7 @@ function attachRomanization(card) {
         romanizationAccepted: rom.accepted,
     };
 }
-function parseCard(chunk, materialType, filePath, index) {
+function parseCard(chunk, defaultType, defaultTags, filePath, index) {
     const lines = chunk.split('\n');
     const h1Line = lines[0];
     const titleMatch = h1Line.match(/^#\s+(.*)$/);
@@ -66,19 +67,50 @@ function parseCard(chunk, materialType, filePath, index) {
     const title = titleMatch[1].trim();
     if (!title)
         return null;
-    const body = lines.slice(1).join('\n').trim();
-    switch (materialType) {
+    const rawBody = lines.slice(1).join('\n').trim();
+    const { meta: cardMeta, rest: bodyAfterFm } = parseCardFrontmatter(rawBody);
+    const body = bodyAfterFm.trim();
+    // Type resolution: card's own type wins, otherwise fall back to the
+    // material's default. A card with neither is unparseable and gets
+    // skipped (validators can surface this to the author).
+    const cardType = (cardMeta.type ?? defaultType);
+    if (!cardType)
+        return null;
+    const tags = dedupe([...defaultTags, ...cardMeta.tags]);
+    let card;
+    switch (cardType) {
         case 'word':
         case 'sentence':
-            return buildAnnotatedCard(title, body, filePath, index);
+            card = buildAnnotatedCard(title, body, filePath, index);
+            break;
         case 'qa':
         case 'code':
-            return buildQACard(title, body, filePath, index);
+            card = buildQACard(title, body, filePath, index);
+            break;
         case 'article':
         case 'snippet':
         default:
-            return buildArticleCard(title, body, filePath, index);
+            card = buildArticleCard(title, body, filePath, index);
+            break;
+    }
+    if (!card)
+        return null;
+    card.type = cardType;
+    card.tags = tags;
+    return card;
+}
+function dedupe(tags) {
+    const seen = new Set();
+    const out = [];
+    for (const t of tags) {
+        if (!t)
+            continue;
+        if (seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
     }
+    return out;
 }
 /**
  * word / sentence: H1 is the typing target. H2/H3/H4 are optional
@@ -102,6 +134,8 @@ function buildAnnotatedCard(title, body, filePath, index) {
         image: h4 || undefined,
         charPlans,
         unknownChars: validated.unknowns,
+        type: '',
+        tags: [],
     };
 }
 /**
@@ -129,6 +163,8 @@ function buildArticleCard(title, body, filePath, index) {
         question: body,
         charPlans,
         unknownChars: validated.unknowns,
+        type: '',
+        tags: [],
     };
 }
 /**
@@ -158,6 +194,8 @@ function buildQACard(title, body, filePath, index) {
         question,
         charPlans,
         unknownChars: validated.unknowns,
+        type: '',
+        tags: [],
     };
 }
 /**