dsh-paper-doc-adapter 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.2.2
+
+- Rework the README first screen. The H1 now names what the plugin checks rather
+  than repeating the package name, and a question-and-answer table and a standards
+  table come before the boundary paragraph.
+
+  The substance is unchanged and the boundary paragraph is verbatim: in a
+  compliance tool that paragraph is what stops a wrong "pass" being read as
+  approval, so it moved rather than shrank. What changed is the order - a reader
+  or an extractor previously met eleven badges, an install command and a
+  disclaimer before learning what the plugin does. The Q&A rows are derived from
+  each plugin's own rules and the standards table from the rule pack's
+  `document`/`number` fields, so no answer and no standard is hand-typed.
+
+  All five languages were restructured together; `check:readmes` holds them to the
+  same section count, install command and configuration keys.
+
+## 0.2.1
+
+- Ship `CHANGELOG.md` and `SECURITY.md` inside the package. `files` is an
+  allowlist and neither was on it, so no release note had ever reached anyone
+  who installed this package, and npm had no changelog section to show.
+## 0.2.0
+
+- Release infrastructure brought to the family standard: `verify:self-contained`,
+  `check:lockfile`, `check:readmes` and `check:citations` gates, a `prepublishOnly` that
+  re-runs the whole chain, SECURITY.md, dependabot, and the OpenSSF Scorecard workflow.
+- `check:citations` enforces the rule this pack's own header states: every `excerpt`
+  must be a verbatim quotation, findable in `rules/evidence/`. Rules that are not
+  traceable yet are listed in `rules/citations-baseline.json`, and that file can only
+  shrink - anything new has to be sourced before it can land.
+- The README install command now names the published package instead of a local tarball.
+- Five-language READMEs hold the same section count and the same configuration keys.
+- Rule pack: 8 rules across PD-001..PD-008.
+- Licensed Apache-2.0.

package/README-es.md

@@ -1,4 +1,25 @@
-# dsh-paper-doc-adapter
+# dsh-paper-doc-adapter — Verificación de la coherencia estructural de un examen analizado: tipo de pregunta, respuesta, puntuación e identificador yotta
+
+`dsh-paper-doc-adapter` lee un examen ya analizado —la cabecera del examen más una fila por pregunta— y comprueba la coherencia estructural interna de ese resultado: que cada pregunta registre su número y su enunciado, que haya una respuesta o una explicación, que la suma de las puntuaciones de las preguntas coincida con la puntuación total que indica la cabecera, que el tipo de pregunta provenga del vocabulario que usted configura, que el coeficiente de dificultad quede dentro de su rango, que los identificadores de pregunta estén presentes y no se repitan, que se registre un punto de conocimiento y que no quede ningún marcador de plantilla en el enunciado.
+
+## Qué responde
+
+| Usted pregunta | Qué responde |
+|---|---|
+| En una fila están vacíos tanto el número como el enunciado, ¿se informa de algo? | Sí. `PD-001` informa de la fila cuyo `questionNo` y `stem` están ambos vacíos, porque pide que se rellene al menos uno de los dos. Comprueba que algo esté puesto, no si la pregunta está bien redactada o el enunciado es riguroso. |
+| Una pregunta tiene número y enunciado, pero ni respuesta ni explicación. | `PD-002` informa de esa fila: pide al menos uno de `answer` y `explanation`. No comprueba si la respuesta es correcta —eso es revisión de un experto de la materia, y el propio paquete lo dice. |
+| Las puntuaciones suman 98 y la cabecera dice 100, ¿se detecta? | Sí. `PD-003` suma la columna `score` y compara el total con el `totalScore` que indica la cabecera del examen, con la tolerancia configurada de 0.01; si el total de la cabecera no es un número analizable, informa de que no pudo ejecutarse en `skipped`. Solo hace la suma: no juzga si el reparto de puntos es razonable. |
+| Nunca declaramos nuestros propios tipos de pregunta. ¿Qué hace la herramienta con esa columna? | `PD-004` informa de que no pudo ejecutarse en `skipped`, porque su lista `values` viene vacía: nombrar los tipos de pregunta es convención de su institución y el motor no codifica ninguna lista. Al configurar sus valores, un `questionType` fuera de ellos se informa; la regla entonces solo comprueba la pertenencia y no hace ninguna validación estructural por tipo de pregunta. |
+| La columna de dificultad trae `1.2` en una fila y `中等` en otra, ¿qué devuelve? | `PD-005` informa del valor que no puede analizar como número y del que queda fuera del rango `min`/`max` configurado, 0–1. Ese rango es convención de su institución, no la única escala: con 1–5 o porcentajes hay que cambiar `min`/`max` o desactivar la regla. Solo comprueba el rango, nunca si la dificultad es adecuada, y está limitada a `info`. |
+| Dos preguntas llevan el mismo identificador yotta. ¿Por qué es peor que uno vacío? | `PD-006` informa del valor repetido, comparando sin espacios, porque importar ese resultado sobrescribiría en silencio una pregunta existente; un identificador vacío solo deja esa pregunta fuera. Si ninguna fila trae identificador, la regla informa de que no pudo ejecutarse en `skipped`. Comprueba presencia y unicidad, y nada más. |
+
+## Normas que sigue
+
+| Documento | Número | Reglas que lo citan |
+|---|---|---|
+| 《试题元数据规范》 | JY/T 0606 系列（本次未取得条文） | PD-001, PD-002, PD-003, PD-006, PD-007, PD-008 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的题型口径） | PD-004 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的难度口径） | PD-005 |
 
 **Boundary:** this plugin checks a **试卷解析结果** for structural self-consistency — that each question records its
 number and stem, that an answer or an explanation is present, that the question scores total the paper's score,

package/README-hi.md

@@ -1,4 +1,25 @@
-# dsh-paper-doc-adapter
+# dsh-paper-doc-adapter — विश्लेषित प्रश्नपत्र की संरचनात्मक संगति की जाँच: प्रश्न-प्रकार, उत्तर, अंक और yotta पहचानकर्ता
+
+`dsh-paper-doc-adapter` एक विश्लेषित प्रश्नपत्र पढ़ता है — प्रश्नपत्र का हेडर और प्रत्येक प्रश्न की एक पंक्ति — और उसी विश्लेषण-परिणाम की आंतरिक संरचनात्मक संगति जाँचता है: क्या प्रत्येक प्रश्न में उसका क्रमांक और प्रश्न-कथन दर्ज है, क्या उत्तर या व्याख्या में से कम से कम एक दर्ज है, क्या सभी प्रश्नों के अंकों का जोड़ हेडर में लिखे कुल अंक के बराबर है, क्या प्रश्न-प्रकार आपके द्वारा कॉन्फ़िगर की गई सूची से आता है, क्या कठिनाई-गुणांक आपकी निर्धारित सीमा के भीतर है, क्या प्रश्न-पहचानकर्ता दर्ज और अद्वितीय हैं, क्या ज्ञान-बिंदु दर्ज है, और क्या प्रश्न-कथन में कोई टेम्पलेट प्लेसहोल्डर शेष नहीं है।
+
+## यह किन सवालों का जवाब देता है
+
+| आपका सवाल | इसका जवाब |
+|---|---|
+| किसी पंक्ति में प्रश्न-क्रमांक और प्रश्न-कथन दोनों खाली हैं — क्या कुछ बताया जाता है? | हाँ। `PD-001` उस पंक्ति को दर्ज करता है जिसमें `questionNo` और `stem` दोनों खाली हैं, क्योंकि वह दोनों में से कम से कम एक भरा होने की अपेक्षा करता है। यह देखता है कि कुछ भरा है, यह नहीं कि प्रश्न अच्छा है या कथन कठोर है। |
+| एक प्रश्न में क्रमांक और कथन हैं, पर न उत्तर है न व्याख्या। | `PD-002` उस पंक्ति को दर्ज करता है: वह `answer` और `explanation` में से कम से कम एक की अपेक्षा करता है। यह नहीं जाँचता कि उत्तर सही है — वह विषय-विशेषज्ञ की समीक्षा है, और नियम-संग्रह स्वयं यही कहता है। |
+| प्रश्नों के अंक जोड़कर 98 बनते हैं और हेडर में 100 लिखा है — क्या यह पकड़ में आता है? | हाँ। `PD-003` `score` कॉलम का जोड़ करता है और उसकी तुलना प्रश्नपत्र के हेडर में लिखे `totalScore` से करता है, कॉन्फ़िगर की गई 0.01 की छूट के साथ; हेडर का कुल अंक संख्या के रूप में पढ़ा न जा सके तो यह `skipped` में बताता है कि वह चल नहीं सका। यह केवल जोड़ देखता है — अंकों का बँटवारा उचित है या नहीं, यह नहीं आँकता। |
+| हमने अपनी प्रश्न-प्रकार सूची कभी नहीं बनाई। प्रश्न-प्रकार कॉलम पर उपकरण क्या करता है? | `PD-004` `skipped` में बताता है कि वह चल नहीं सका, क्योंकि उसकी `values` सूची खाली आती है: प्रश्न-प्रकारों के नाम आपकी संस्था की परिपाटी हैं और इंजन कोई सूची कठोरता से नहीं रखता। अपने मान कॉन्फ़िगर करने पर सूची से बाहर का `questionType` दर्ज होता है; तब यह नियम केवल सूची-सदस्यता देखता है और प्रश्न-प्रकार के अनुसार कोई संरचना-जाँच नहीं करता। |
+| कठिनाई कॉलम में एक पंक्ति में `1.2` है और दूसरी में `中等` — क्या लौटता है? | `PD-005` उस मान को दर्ज करता है जिसे संख्या के रूप में नहीं पढ़ा जा सकता, और उसे भी जो कॉन्फ़िगर की गई `min`/`max` सीमा 0–1 से बाहर है। यह सीमा आपकी संस्था की परिपाटी है, एकमात्र पैमाना नहीं — 1–5 या प्रतिशत के लिए `min`/`max` बदलें या नियम बंद करें। यह केवल सीमा देखता है, कठिनाई उपयुक्त है या नहीं यह कभी नहीं, और यह `info` पर सीमित है। |
+| दो प्रश्नों पर एक ही yotta पहचानकर्ता है। यह खाली पहचानकर्ता से बुरा क्यों है? | `PD-006` दोहराया गया मान दर्ज करता है, तुलना में खाली स्थान छोड़ देता है, क्योंकि यह विश्लेषण-परिणाम आयात करने पर मौजूद प्रश्न चुपचाप अधिलिखित हो जाएगा; खाली पहचानकर्ता केवल उस एक प्रश्न को बाहर रखता है। किसी पंक्ति में पहचानकर्ता न भरा हो तो नियम `skipped` में बताता है कि वह चल नहीं सका। यह उपस्थिति और अद्वितीयता देखता है, उससे आगे कुछ नहीं। |
+
+## यह किन मानकों पर आधारित है
+
+| दस्तावेज़ | संख्यांक | इन्हें उद्धृत करने वाले नियम |
+|---|---|---|
+| 《试题元数据规范》 | JY/T 0606 系列（本次未取得条文） | PD-001, PD-002, PD-003, PD-006, PD-007, PD-008 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的题型口径） | PD-004 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的难度口径） | PD-005 |
 
 **Boundary:** this plugin checks a **试卷解析结果** for structural self-consistency — that each question records its
 number and stem, that an answer or an explanation is present, that the question scores total the paper's score,

package/README-pt.md

@@ -1,4 +1,25 @@
-# dsh-paper-doc-adapter
+# dsh-paper-doc-adapter — Verificação da coerência estrutural de um exame analisado: tipo de questão, resposta, pontuação e identificador yotta
+
+`dsh-paper-doc-adapter` lê um exame já analisado —o cabeçalho do exame mais uma linha por questão— e verifica a coerência estrutural interna desse resultado: se cada questão regista o seu número e o seu enunciado, se há uma resposta ou uma explicação, se a soma das pontuações das questões coincide com a pontuação total indicada no cabeçalho, se o tipo de questão vem do vocabulário que você configura, se o coeficiente de dificuldade fica dentro do seu intervalo, se os identificadores de questão estão presentes e não se repetem, se um ponto de conhecimento está registado e se não resta nenhum marcador de modelo no enunciado.
+
+## O que ele responde
+
+| Você pergunta | O que ele responde |
+|---|---|
+| Numa linha estão vazios tanto o número como o enunciado — isso é reportado? | Sim. `PD-001` reporta a linha cujo `questionNo` e `stem` estão ambos vazios, porque exige que pelo menos um dos dois seja preenchido. Verifica que algo está preenchido, não se a questão está bem redigida ou o enunciado é rigoroso. |
+| Uma questão tem número e enunciado, mas nem resposta nem explicação. | `PD-002` reporta essa linha: exige pelo menos um de `answer` e `explanation`. Não verifica se a resposta está correta — isso é revisão de um especialista da matéria, e o próprio pacote o diz. |
+| As pontuações somam 98 e o cabeçalho diz 100 — isso é detetado? | Sim. `PD-003` soma a coluna `score` e compara o total com o `totalScore` indicado no cabeçalho do exame, com a tolerância configurada de 0.01; se o total do cabeçalho não for um número analisável, reporta em `skipped` que não pôde ser executada. Faz apenas a soma: não julga se a distribuição dos pontos é razoável. |
+| Nunca declarámos os nossos próprios tipos de questão. O que a ferramenta faz com essa coluna? | `PD-004` reporta em `skipped` que não pôde ser executada, porque a sua lista `values` vem vazia: nomear os tipos de questão é convenção da sua instituição e o motor não codifica nenhuma lista. Ao configurar os seus valores, um `questionType` fora deles é reportado; a regra passa então a verificar apenas a pertença e não faz nenhuma validação estrutural por tipo de questão. |
+| A coluna da dificuldade traz `1.2` numa linha e `中等` noutra — o que devolve? | `PD-005` reporta o valor que não consegue analisar como número e o que fica fora do intervalo `min`/`max` configurado, 0–1. Esse intervalo é convenção da sua instituição, não a única escala: com 1–5 ou percentagens é preciso alterar `min`/`max` ou desativar a regra. Verifica apenas o intervalo, nunca se a dificuldade é adequada, e está limitada a `info`. |
+| Duas questões trazem o mesmo identificador yotta. Porque é pior do que um vazio? | `PD-006` reporta o valor repetido, comparando sem espaços, porque importar esse resultado sobrescreveria silenciosamente uma questão existente; um identificador vazio apenas deixa essa questão de fora. Se nenhuma linha trouxer identificador, a regra reporta em `skipped` que não pôde ser executada. Verifica presença e unicidade, e nada além disso. |
+
+## Normas que segue
+
+| Documento | Número | Regras que o citam |
+|---|---|---|
+| 《试题元数据规范》 | JY/T 0606 系列（本次未取得条文） | PD-001, PD-002, PD-003, PD-006, PD-007, PD-008 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的题型口径） | PD-004 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的难度口径） | PD-005 |
 
 **Boundary:** this plugin checks a **试卷解析结果** for structural self-consistency — that each question records its
 number and stem, that an answer or an explanation is present, that the question scores total the paper's score,

package/README-zh.md

@@ -1,4 +1,25 @@
-# dsh-paper-doc-adapter
+# dsh-paper-doc-adapter — 试卷解析结构核对
+
+`dsh-paper-doc-adapter` 读取一份试卷解析结果——试卷表头加每道题一行——核对这份解析结果自身的结构自洽：每道题是否填写了题号与题干、是否填写了答案或解析、各题分值合计是否等于表头写的试卷总分、题型取值是否出自你配置的口径、难度系数是否落在你配置的范围内、题目标识是否齐备且唯一、是否标注了知识点、题干栏是否残留模板占位符。
+
+## 它回答什么问题
+
+| 你会问 | 它怎么答 |
+|---|---|
+| 某行的题号与题干都是空的，会被报出吗？ | 会。`PD-001` 只要求 `questionNo` 与 `stem` 至少填一项，两项都空才报出该行。它只核对是否填写，不判断题目出得好不好、题干是否严谨。 |
+| 一道题有题号和题干，但答案与解析都没有。 | `PD-002` 会报出该行：它要求 `answer` 与 `explanation` 至少填一项。它不核对答案是否正确——那需要学科专家审题，规则库自己也这么写明。 |
+| 各题分值加总为 98，表头写的是 100，能查出来吗？ | 能。`PD-003` 把 `score` 栏加总，与试卷表头写的 `totalScore` 相比，允许配置的 0.01 偏差；表头总分不是可解析的数字时，本条报告自己进入 `skipped`，而不是静默通过。它只做加法核对，不判断分值分配是否合理。 |
+| 我们还没有配置自己的题型口径，工具会怎么处理题型栏？ | `PD-004` 会报告自己进入 `skipped`：它的 `values` 出厂为空，题型命名属你所在机构的口径，引擎不硬编码任何清单。配置了取值以后，不在册的 `questionType` 会被报出；此时本条只核对是否在册，也不针对题型做结构校验。 |
+| 难度栏一行写 `1.2`，一行写 `中等`，会返回什么？ | `PD-005` 会把无法解析为数字的值报出，也会把落在配置范围 0–1 之外的值报出。0–1 是本机构口径、不是唯一刻度——用 1–5 或百分制就改 `min`/`max` 或停用本条。它只核对范围，不判断难度是否恰当，且封顶 `info`。 |
+| 两道题用了同一个 yotta 标识，为什么这比空着更糟？ | `PD-006` 会报出重复的值（比较时忽略空白字符），因为导入这份解析结果会静默覆盖已有题目；空标识只是这道题入不了库。整栏都没填时，本条报告自己进入 `skipped`。它只核对齐备与唯一，此外不作判断。 |
+
+## 依据的标准
+
+| 文件 | 文号 | 引用它的规则 |
+|---|---|---|
+| 《试题元数据规范》 | JY/T 0606 系列（本次未取得条文） | PD-001, PD-002, PD-003, PD-006, PD-007, PD-008 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的题型口径） | PD-004 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的难度口径） | PD-005 |
 
 **Boundary:** this plugin checks a **试卷解析结果** for structural self-consistency — that each question records its
 number and stem, that an answer or an explanation is present, that the question scores total the paper's score,

package/README.md

@@ -1,4 +1,25 @@
-# dsh-paper-doc-adapter
+# dsh-paper-doc-adapter — Parsed exam paper structural self-consistency check across question type, answer, score and yotta identifier
+
+`dsh-paper-doc-adapter` reads one parsed exam paper — the paper header plus one row per question — and checks that parse result's own structural self-consistency: that each question records its number and stem, that an answer or an explanation is present, that the question scores total the paper score the header states, that the question type comes from the vocabulary you configure, that the difficulty coefficient falls inside your range, that question identifiers are present and unique, that a knowledge point is recorded, and that no template placeholder survives in the stem.
+
+## What it answers
+
+| You ask | What it answers |
+|---|---|
+| Both the question number and the stem are blank on a row — does the check say anything? | Yes. `PD-001` reports a row whose `questionNo` and `stem` are both empty, because it asks for at least one of the two. It checks that something is filled, not whether the question is well written or the stem rigorous. |
+| A question has its number and stem, but neither an answer nor an explanation. | `PD-002` reports that row: it asks for at least one of `answer` and `explanation`. It does not check whether the answer is correct — that is subject-expert review, and the pack says as much. |
+| The question scores add up to 98 while the header says 100 — is that caught? | Yes. `PD-003` adds the `score` column and compares the total with the `totalScore` the paper header states, allowing the configured tolerance of 0.01; if the header total is not a parseable number it reports itself in `skipped` instead. It only does the addition — whether the marks are distributed sensibly is not judged. |
+| We never listed our own question types. What does the tool do with the question type column? | `PD-004` reports itself in `skipped`, because its `values` list ships empty: naming question types is your institution's convention and the engine hard-codes no list. Once you configure your values, a `questionType` outside them is reported; the rule then checks membership only, and it performs no question-type-specific structure check. |
+| The difficulty column holds `1.2` in one row and `中等` in another — what comes back? | `PD-005` reports the value it cannot parse as a number and the value outside the configured `min`/`max` range of 0–1. That range is your institution's convention, not the only scale — 1–5 or a percentage needs `min`/`max` changed or the rule disabled. It checks the range only, never whether the difficulty is appropriate, and it is capped at `info`. |
+| Two questions carry the same yotta identifier. Why is that worse than a blank one? | `PD-006` reports the repeated value, comparing with whitespace ignored, because importing that parse result would silently overwrite an existing question; a blank identifier only keeps that one question out. With no identifier filled anywhere the rule reports itself in `skipped`. It checks presence and uniqueness, and nothing beyond that. |
+
+## Standards it follows
+
+| Document | Number | Cited by rules |
+|---|---|---|
+| 《试题元数据规范》 | JY/T 0606 系列（本次未取得条文） | PD-001, PD-002, PD-003, PD-006, PD-007, PD-008 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的题型口径） | PD-004 |
+| 本机构题库与命题口径（本机构配置） | 无统一标准（本条依据为本机构配置的难度口径） | PD-005 |
 
 **Boundary:** this plugin checks a **试卷解析结果** for structural self-consistency — that each question records its
 number and stem, that an answer or an explanation is present, that the question scores total the paper's score,

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security vulnerabilities **privately** through GitHub's private
+vulnerability reporting:
+
+**Security → Report a vulnerability** at
+https://github.com/PerryLink/dsh-paper-doc-adapter/security/advisories/new
+
+Do **not** open a public issue for security findings.
+
+Before reporting, **sanitize everything you paste**: remove tokens, API keys,
+credentials, authorization headers, session contents, and personal data. Logs
+without secrets only.
+
+## Scope note
+
+This plugin is an offline checker. It reads the material you hand it and
+compares it against a versioned rule pack; it makes no network calls and no
+model calls, and it stores nothing.
+
+## What to include
+
+- affected package version (and DeepSeek Harness runtime version)
+- a minimal reproduction
+- your impact assessment
+
+## Response expectations
+
+- acknowledgement within **7 days**
+- status updates at least every **14 days** until resolution
+- coordinated disclosure: the fix and advisory are prepared first; the finding
+  is disclosed publicly after the fix ships
+
+## Credits and disclosure
+
+- reporters are credited in the advisory and CHANGELOG unless they ask to stay anonymous
+- advisories follow GitHub's advisory workflow and are published together with the fix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-paper-doc-adapter",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "试卷解析结构核对（按题型、答案、分值与 yotta 标识核对试卷结构自洽，仅提示差异，不作出定性结论）",
   "type": "module",
   "main": "lib/index.mjs",
@@ -23,7 +23,9 @@
     "README-hi.md",
     "locale/*.json",
     "icon.svg",
-    "rules"
+    "rules",
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "build": "tsdown",
@@ -32,7 +34,7 @@
     "verify:self-contained": "node scripts/verify-self-contained.mjs",
     "check:lockfile": "node scripts/check-lockfile-drift.mjs",
     "check:readmes": "node scripts/check-readme-sync.mjs",
-    "prepublishOnly": "pnpm run typecheck && pnpm test && pnpm run build && pnpm run verify:self-contained && pnpm run check:readmes && pnpm run check:citations",
+    "prepublishOnly": "pnpm run typecheck && pnpm test && pnpm run build && pnpm run verify:self-contained && pnpm run check:lockfile && pnpm run check:readmes && pnpm run check:citations",
     "prepare": "tsdown",
     "check:citations": "node scripts/check-citations.mjs"
   },