@case-framework/survey-assistant 0.8.0 → 0.9.0

package/dist/{authoring-references-DbuOKerg.mjs → authoring-references-CmwLc_C8.mjs}

@@ -15,29 +15,34 @@ const surveyAuthoringReferenceTopics = [
 	"source-material-surveys",
 	"localization",
 	"rich-text-content",
-	"item-types",
-	"embedded-forms",
+	"element-types",
+	"follow-ups",
 	"expressions",
 	"assistant-operations",
 	"fair-by-design",
 	"survey-quality"
 ];
-const ITEM_TYPE_SECTION_HEADINGS = {
-	group: "group",
-	"page-break": "page-break",
-	infoItem: "infoItem",
-	consentItem: "consentItem",
-	choiceItem: "choiceItem",
-	formItem: "formItem",
+const ELEMENT_TYPE_SECTION_HEADINGS = {
+	information: "information",
+	text: "text",
+	number: "number",
+	date: "date",
+	boolean: "boolean",
+	choice: "choice",
+	consent: "consent",
 	choiceMatrix: "choiceMatrix",
 	formMatrix: "formMatrix"
 };
-const builtInSurveyAuthoringItemTypes = Object.freeze(Object.keys(ITEM_TYPE_SECTION_HEADINGS));
-const extractLevelTwoSection = (markdown, heading) => {
+const builtInSurveyAuthoringElementTypes = Object.freeze(Object.keys(ELEMENT_TYPE_SECTION_HEADINGS));
+const extractSection = (markdown, heading, level = 2) => {
 	const lines = markdown.split("\n");
-	const sectionStart = lines.findIndex((line) => line.trim() === `## ${heading}`);
+	const prefix = "#".repeat(level);
+	const sectionStart = lines.findIndex((line) => line.trim() === `${prefix} ${heading}`);
 	if (sectionStart < 0) return;
-	const nextSectionOffset = lines.slice(sectionStart + 1).findIndex((line) => line.startsWith("## "));
+	const nextSectionOffset = lines.slice(sectionStart + 1).findIndex((line) => {
+		const match = /^(#+) /.exec(line);
+		return match !== null && match[1].length <= level;
+	});
 	const sectionEnd = nextSectionOffset < 0 ? lines.length : sectionStart + 1 + nextSectionOffset;
 	return lines.slice(sectionStart, sectionEnd).join("\n").trim();
 };
@@ -72,15 +77,15 @@ const surveyAuthoringReferences = {
 		content: loadReference("rich-text-content.md"),
 		loadWhen: "Load before authoring or changing meaningful formatting, links, images, headings, lists, info boxes, separators, footnotes, or existing structured rich-text content; do not load it for ordinary unformatted plain text."
 	},
-	"item-types": {
-		title: "Item types",
-		content: loadReference("item-types.md"),
-		loadWhen: "Load with itemType before creating or changing an item when its configuration, response behavior, or content surfaces are not already fully specified by the current capability and focused operation contract; omit itemType only for a genuine cross-type comparison."
+	"element-types": {
+		title: "Element types",
+		content: loadReference("element-types.md"),
+		loadWhen: "Load with elementType before creating or changing an item when its configuration, response behavior, or content surfaces are not already fully specified by the current capability and focused operation contract; omit elementType only for a genuine cross-type comparison."
 	},
-	"embedded-forms": {
-		title: "Choice option embedded forms",
-		content: loadReference("embedded-forms.md"),
-		loadWhen: "Load before creating or changing a choice-option follow-up or embedded form, including \"Other, specify\", option-specific inputs, embedded field groups, or embedded-form layout and translations."
+	"follow-ups": {
+		title: "Option-inline follow-ups",
+		content: loadReference("follow-ups.md"),
+		loadWhen: "Load before creating or changing a choice-option follow-up, including \"Other, specify\", option-specific inputs, semantic sections, layout and owner-role translations."
 	},
 	expressions: {
 		title: "Expressions",
@@ -90,7 +95,7 @@ const surveyAuthoringReferences = {
 	"assistant-operations": {
 		title: "Assistant operations",
 		content: loadReference("assistant-operations.md"),
-		loadWhen: "Load with operationKind before the first survey_change call when the exact canonical fields of that operation are not already present in the current turn; add itemType when item-specific configuration or capability guidance is needed. Prefer compact detail and use full only for protocol debugging."
+		loadWhen: "Load with operationKind before the first survey_change call when the exact canonical fields of that operation are not already present in the current turn; add elementType when item-specific configuration or capability guidance is needed. Prefer compact detail and use full only for protocol debugging."
 	},
 	"fair-by-design": {
 		title: "FAIR-by-design survey authoring",
@@ -106,19 +111,22 @@ const surveyAuthoringReferences = {
 const formatSurveyAuthoringReferenceRoutingInstructions = () => [
 	"Authoring-reference routing rules:",
 	"Load a relevant focused reference before the first affected mutation or substantive advice, not after guessing a payload or learning through validator failures. Do not reload a reference when its exact relevant contract is already present in the current turn. References define stable authoring conventions and payload grammar; current survey state and currently available runtime references still come from inspection and context tools.",
-	"For installed capability-specific references, use the capability manifest's advertised reference topics. Load a relevant topic with itemType before changing unfamiliar capability configuration or behavior.",
+	"For installed capability-specific references, use the capability manifest's advertised reference topics. Load a relevant topic with elementType before changing unfamiliar capability configuration or behavior.",
 	...surveyAuthoringReferenceTopics.map((topic) => `- ${topic}: ${surveyAuthoringReferences[topic].loadWhen}`)
 ].join("\n");
-const getBuiltInItemTypeAuthoringReference = (itemType) => {
-	const heading = ITEM_TYPE_SECTION_HEADINGS[itemType];
+const getBuiltInElementTypeAuthoringReference = (elementType) => {
+	const heading = ELEMENT_TYPE_SECTION_HEADINGS[elementType];
 	if (!heading) return;
-	const content = extractLevelTwoSection(surveyAuthoringReferences["item-types"].content, heading);
-	return content ? {
-		title: `${heading} item type`,
-		content
-	} : void 0;
+	const content = extractSection(surveyAuthoringReferences["element-types"].content, heading);
+	if (!content) return void 0;
+	const exampleHeading = elementType === "choice" ? "Full worked example: a single-choice question" : elementType === "text" || elementType === "number" ? "Full worked example: a composed question with two inputs" : void 0;
+	const example = exampleHeading ? extractSection(surveyAuthoringReferences["assistant-operations"].content, exampleHeading, 3) : void 0;
+	return {
+		title: `${heading} element type`,
+		content: example ? `${content}\n\n${example}` : content
+	};
 };
 //#endregion
-export { surveyAuthoringReferences as a, surveyAuthoringReferenceTopics as i, formatSurveyAuthoringReferenceRoutingInstructions as n, getBuiltInItemTypeAuthoringReference as r, builtInSurveyAuthoringItemTypes as t };
+export { surveyAuthoringReferences as a, surveyAuthoringReferenceTopics as i, formatSurveyAuthoringReferenceRoutingInstructions as n, getBuiltInElementTypeAuthoringReference as r, builtInSurveyAuthoringElementTypes as t };
 
-//# sourceMappingURL=authoring-references-DbuOKerg.mjs.map
+//# sourceMappingURL=authoring-references-CmwLc_C8.mjs.map

package/dist/authoring-references-CmwLc_C8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-references-CmwLc_C8.mjs","names":[],"sources":["../../../node_modules/.pnpm/tsdown@0.23.0_@volar+typescript@2.4.28_typescript@6.0.3__typescript@6.0.3_unrun@0.2.39/node_modules/tsdown/esm-shims.js","../src/server/authoring-references.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ */ getDirname()\nexport const __filename = /* @__PURE__ */ getFilename()\n","import { readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\n\nconst loadReference = (fileName: string) =>\n  readFileSync(resolve(__dirname, \"references\", fileName), \"utf8\").trim();\n\nexport const surveyAuthoringReferenceTopics = [\n  \"core-rules\",\n  \"survey-data-model\",\n  \"response-variables\",\n  \"source-material-surveys\",\n  \"localization\",\n  \"rich-text-content\",\n  \"element-types\",\n  \"follow-ups\",\n  \"expressions\",\n  \"assistant-operations\",\n  \"fair-by-design\",\n  \"survey-quality\",\n] as const;\n\nexport type SurveyAuthoringReferenceTopic = (typeof surveyAuthoringReferenceTopics)[number];\n\ntype SurveyAuthoringReferenceEntry = {\n  title: string;\n  content: string;\n  loadWhen: string;\n};\n\nconst ELEMENT_TYPE_SECTION_HEADINGS: Readonly<Record<string, string>> = {\n  information: \"information\",\n  text: \"text\",\n  number: \"number\",\n  date: \"date\",\n  boolean: \"boolean\",\n  choice: \"choice\",\n  consent: \"consent\",\n  choiceMatrix: \"choiceMatrix\",\n  formMatrix: \"formMatrix\",\n};\n\nexport const builtInSurveyAuthoringElementTypes = Object.freeze(\n  Object.keys(ELEMENT_TYPE_SECTION_HEADINGS),\n);\n\nconst extractSection = (markdown: string, heading: string, level = 2): string | undefined => {\n  const lines = markdown.split(\"\\n\");\n  const prefix = \"#\".repeat(level);\n  const sectionStart = lines.findIndex((line) => line.trim() === `${prefix} ${heading}`);\n  if (sectionStart < 0) {\n    return undefined;\n  }\n\n  const nextSectionOffset = lines.slice(sectionStart + 1).findIndex((line) => {\n    const match = /^(#+) /.exec(line);\n    return match !== null && match[1].length <= level;\n  });\n  const sectionEnd = nextSectionOffset < 0 ? lines.length : sectionStart + 1 + nextSectionOffset;\n\n  return lines.slice(sectionStart, sectionEnd).join(\"\\n\").trim();\n};\n\nexport const surveyAuthoringReferences = {\n  \"core-rules\": {\n    title: \"Core authoring rules\",\n    content: loadReference(\"core-rules.md\"),\n    loadWhen:\n      \"Load when the task depends on canonical tool choice, validation/apply semantics, identifier handling, or another cross-cutting authoring rule that the current turn has not already established.\",\n  },\n  \"response-variables\": {\n    title: \"Response variables and coding\",\n    content: loadReference(\"response-variables.md\"),\n    loadWhen:\n      \"Load before creating response inputs, changing variable names, option codes, matrix coding components, or export settings. Inspect current response slots for exact IDs and domains.\",\n  },\n  \"survey-data-model\": {\n    title: \"Survey data model\",\n    content: loadReference(\"survey-data-model.md\"),\n    loadWhen:\n      \"Load before reasoning about raw survey storage, hierarchy, ids, translation maps, assets, template values, or any direct survey-json-patch path whose exact location has not already been inspected and documented in the current turn.\",\n  },\n  \"source-material-surveys\": {\n    title: \"Source-material survey implementation\",\n    content: loadReference(\"source-material-surveys.md\"),\n    loadWhen:\n      \"Load before implementing or adapting a questionnaire, document, image, or other supplied source material so completeness, respondent-input mapping, meaningful layout, language, and digital adaptation rules are available before the first mutation.\",\n  },\n  localization: {\n    title: \"Survey localization\",\n    content: loadReference(\"localization.md\"),\n    loadWhen:\n      \"Load before adding, removing, translating, or assessing a survey locale, including requests for localization completeness or locale lifecycle changes.\",\n  },\n  \"rich-text-content\": {\n    title: \"Rich text content\",\n    content: loadReference(\"rich-text-content.md\"),\n    loadWhen:\n      \"Load before authoring or changing meaningful formatting, links, images, headings, lists, info boxes, separators, footnotes, or existing structured rich-text content; do not load it for ordinary unformatted plain text.\",\n  },\n  \"element-types\": {\n    title: \"Element types\",\n    content: loadReference(\"element-types.md\"),\n    loadWhen:\n      \"Load with elementType before creating or changing an item when its configuration, response behavior, or content surfaces are not already fully specified by the current capability and focused operation contract; omit elementType only for a genuine cross-type comparison.\",\n  },\n  \"follow-ups\": {\n    title: \"Option-inline follow-ups\",\n    content: loadReference(\"follow-ups.md\"),\n    loadWhen:\n      'Load before creating or changing a choice-option follow-up, including \"Other, specify\", option-specific inputs, semantic sections, layout and owner-role translations.',\n  },\n  expressions: {\n    title: \"Expressions\",\n    content: loadReference(\"expressions.md\"),\n    loadWhen:\n      \"Load before the first survey_expression prepare call for expression, condition, validation-expression, prefill, or template-value work unless the exact relevant JsonExpression and mutation shapes were already supplied by a current-turn authoring reference. survey_expression context supplies currently available runtime references and value types, but it does not replace the grammar reference. Expressions are not assumed to be survey-response-only; use the references and variable sources supported by the current runtime and reference.\",\n  },\n  \"assistant-operations\": {\n    title: \"Assistant operations\",\n    content: loadReference(\"assistant-operations.md\"),\n    loadWhen:\n      \"Load with operationKind before the first survey_change call when the exact canonical fields of that operation are not already present in the current turn; add elementType when item-specific configuration or capability guidance is needed. Prefer compact detail and use full only for protocol debugging.\",\n  },\n  \"fair-by-design\": {\n    title: \"FAIR-by-design survey authoring\",\n    content: loadReference(\"fair-by-design.md\"),\n    loadWhen:\n      \"Load before advising or editing when FAIR, interoperability, harmonization, cross-study reuse, stable coding, value sets, missingness semantics, metadata, provenance, versioning, standard instruments, controlled vocabularies, or machine-readable export is material; do not impose it on ordinary authoring.\",\n  },\n  \"survey-quality\": {\n    title: \"Survey quality review\",\n    content: loadReference(\"survey-quality.md\"),\n    loadWhen:\n      \"Load before a substantive questionnaire-quality critique, wording or flow review, respondent-burden assessment, or recommendations about measurement quality; it is not required for a purely technical defect check.\",\n  },\n} as const satisfies Record<SurveyAuthoringReferenceTopic, SurveyAuthoringReferenceEntry>;\n\nexport const formatSurveyAuthoringReferenceRoutingInstructions = (): string =>\n  [\n    \"Authoring-reference routing rules:\",\n    \"Load a relevant focused reference before the first affected mutation or substantive advice, not after guessing a payload or learning through validator failures. Do not reload a reference when its exact relevant contract is already present in the current turn. References define stable authoring conventions and payload grammar; current survey state and currently available runtime references still come from inspection and context tools.\",\n    \"For installed capability-specific references, use the capability manifest's advertised reference topics. Load a relevant topic with elementType before changing unfamiliar capability configuration or behavior.\",\n    ...surveyAuthoringReferenceTopics.map(\n      (topic) => `- ${topic}: ${surveyAuthoringReferences[topic].loadWhen}`,\n    ),\n  ].join(\"\\n\");\n\nexport const getBuiltInElementTypeAuthoringReference = (\n  elementType: string,\n): { title: string; content: string } | undefined => {\n  const heading = ELEMENT_TYPE_SECTION_HEADINGS[elementType];\n  if (!heading) {\n    return undefined;\n  }\n\n  const content = extractSection(surveyAuthoringReferences[\"element-types\"].content, heading);\n  if (!content) return undefined;\n  // Keep executable examples in one source while retaining them in focused lookups.\n  // Most authoring turns deliberately never load the full operations catalog.\n  const exampleHeading =\n    elementType === \"choice\"\n      ? \"Full worked example: a single-choice question\"\n      : elementType === \"text\" || elementType === \"number\"\n        ? \"Full worked example: a composed question with two inputs\"\n        : undefined;\n  const example = exampleHeading\n    ? extractSection(surveyAuthoringReferences[\"assistant-operations\"].content, exampleHeading, 3)\n    : undefined;\n  return {\n    title: `${heading} element type`,\n    content: example ? `${content}\\n\\n${example}` : content,\n  };\n};\n"],"x_google_ignoreList":[0],"mappings":"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"}