@thinkingsage/kanon 0.8.0

package/src/rosetta/builtins/sources/kiro-power.ts

@@ -0,0 +1,285 @@
+/**
+ * Rosetta Stone — Kiro Power Source Translator
+ *
+ * Pure translator for the `kiro-power` format:
+ * - Consumes `POWER.md` → extracts frontmatter (name, description, keywords) and body
+ * - Consumes `steering/*.md` files → maps to workflows
+ * - Preserves any other files found
+ * - Maps power-specific fields: `globs` → `file_patterns`, `alwaysApply` → `inclusion`
+ * - Sets `type: "skill"`, `harnesses: ["kiro"]`, `harness-config: { kiro: { format: "power" } }`
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 2.9, 4.1, 4.2, 4.3, 4.5, 13.7, 14.3
+ */
+
+import matter from "gray-matter";
+
+import type {
+	KnowledgeArtifact,
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { codePointCompare } from "../../contracts";
+import { createDiagnostic } from "../../diagnostics";
+import type {
+	SourceTranslationOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+import { SourceAccountant } from "../../source-accounting";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a kiro-power document set into a canonical KnowledgeArtifact candidate.
+ *
+ * Expected documents:
+ * - `POWER.md` (required): YAML frontmatter + Markdown body
+ * - `steering/*.md` (optional): mapped to workflows
+ * - Other files: preserved
+ */
+export function translateKiroPower(
+	documents: readonly SourceDocument[],
+	context: SourceTranslatorContext,
+): SourceTranslationOutput {
+	const accountant = new SourceAccountant();
+	const diagnostics: TranslationDiagnostic[] = [];
+
+	// Find POWER.md
+	const powerDoc = documents.find((d) => d.path === "POWER.md");
+	if (!powerDoc) {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_MISSING_KNOWLEDGE_MD", {
+				formatId: "kiro-power",
+				message: "POWER.md not found in the provided document set.",
+				source: { path: "POWER.md" as NormalizedRelativePath },
+			}),
+		);
+		// Preserve all documents since we cannot parse
+		for (const doc of documents) {
+			accountant.preserve(doc.path);
+		}
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	// Parse POWER.md frontmatter
+	const rawContent =
+		typeof powerDoc.content === "string"
+			? powerDoc.content
+			: new TextDecoder().decode(powerDoc.content);
+
+	let parsed: matter.GrayMatterFile<string>;
+	try {
+		parsed = matter(rawContent);
+	} catch {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_INVALID_FRONTMATTER", {
+				formatId: "kiro-power",
+				message: "The frontmatter YAML in POWER.md could not be parsed.",
+				source: { path: "POWER.md" as NormalizedRelativePath },
+			}),
+		);
+		for (const doc of documents) {
+			accountant.preserve(doc.path);
+		}
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	accountant.consume("POWER.md");
+
+	const sourceFm = parsed.data as Record<string, unknown>;
+	const body = parsed.content.trim();
+
+	// Resolve artifact name from caller context or frontmatter
+	const artifactNameHint = context.callerContext?.artifactNameHint as
+		| string
+		| undefined;
+	const name = String(sourceFm.name || artifactNameHint || "unnamed-power");
+
+	// Map fields from source frontmatter to canonical
+	accountant.mapField("POWER.md", "name", "name", false);
+	accountant.mapField("POWER.md", "description", "description", false);
+	accountant.mapField("POWER.md", "keywords", "keywords", false);
+
+	// Map power-specific fields
+	const filePatterns = mapGlobsToFilePatterns(sourceFm, accountant);
+	const inclusion = mapAlwaysApplyToInclusion(sourceFm, accountant);
+
+	// Collect steering/ files as workflows
+	const steeringDocs = documents
+		.filter((d) => d.path.startsWith("steering/") && d.path.endsWith(".md"))
+		.sort((a, b) => codePointCompare(a.path, b.path));
+
+	const workflows = steeringDocs.map((doc) => {
+		accountant.consume(doc.path);
+		const content =
+			typeof doc.content === "string"
+				? doc.content
+				: new TextDecoder().decode(doc.content);
+		// Strip the steering/ prefix for the workflow filename
+		const filename = doc.path.slice("steering/".length);
+		// Name derived from filename without extension
+		const name = filename.replace(/\.md$/, "");
+		return { name, filename, content };
+	});
+
+	// Preserve any files that are neither POWER.md nor in steering/
+	for (const doc of documents) {
+		if (doc.path === "POWER.md") continue;
+		if (doc.path.startsWith("steering/") && doc.path.endsWith(".md")) continue;
+		accountant.preserve(doc.path);
+	}
+
+	// Apply defaults for fields not in source
+	const appliedDefaults: Array<{
+		field: string;
+		value: unknown;
+		rule: string;
+	}> = [];
+
+	const displayName = String(sourceFm.displayName || name);
+	if (!sourceFm.displayName) {
+		appliedDefaults.push({
+			field: "displayName",
+			value: displayName,
+			rule: "kiro-power-default-displayName",
+		});
+	}
+
+	const description = String(sourceFm.description || "");
+	const keywords = Array.isArray(sourceFm.keywords)
+		? sourceFm.keywords.map(String)
+		: [];
+
+	const author = String(sourceFm.author || "");
+	if (!sourceFm.author) {
+		appliedDefaults.push({
+			field: "author",
+			value: "",
+			rule: "kiro-power-default-author",
+		});
+	}
+
+	const version = "0.1.0";
+	appliedDefaults.push({
+		field: "version",
+		value: version,
+		rule: "kiro-power-default-version",
+	});
+
+	// Emit diagnostics for applied defaults
+	for (const def of appliedDefaults) {
+		accountant.applyDefault(def.field, def.value, def.rule);
+		diagnostics.push(
+			createDiagnostic("RS_DEFAULT_APPLIED", {
+				formatId: "kiro-power",
+				message: `Default applied for "${def.field}": ${JSON.stringify(def.value)}`,
+				source: { path: "POWER.md" as NormalizedRelativePath },
+			}),
+		);
+	}
+
+	// Build canonical candidate
+	const candidate: KnowledgeArtifact = {
+		name,
+		frontmatter: {
+			name,
+			displayName,
+			description,
+			keywords,
+			author,
+			version,
+			harnesses: ["kiro"],
+			type: "skill",
+			inclusion,
+			categories: ["documentation"],
+			ecosystem: [],
+			depends: [],
+			enhances: [],
+			maturity: "stable",
+			trust: "community",
+			audience: "intermediate",
+			"model-assumptions": [],
+			collections: [],
+			"inherit-hooks": false,
+			outcomes: [],
+			"harness-config": { kiro: { format: "power" } },
+			...(filePatterns.length > 0 ? { file_patterns: filePatterns } : {}),
+		},
+		body,
+		hooks: [],
+		mcpServers: [],
+		workflows,
+		sourcePath: "POWER.md",
+		extraFields: {},
+		bodyOverrides: {},
+	};
+
+	return {
+		candidate,
+		diagnostics,
+		consumedPaths: accountant.getConsumedPaths(),
+		preservedPaths: accountant.getPreservedPaths(),
+	};
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Field Mappers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Map `globs` source field to `file_patterns` canonical field.
+ */
+function mapGlobsToFilePatterns(
+	sourceFm: Record<string, unknown>,
+	accountant: SourceAccountant,
+): string[] {
+	if (!sourceFm.globs) return [];
+	accountant.mapField("POWER.md", "globs", "file_patterns", true);
+	if (Array.isArray(sourceFm.globs)) {
+		return sourceFm.globs.map(String);
+	}
+	if (typeof sourceFm.globs === "string") {
+		return [sourceFm.globs];
+	}
+	return [];
+}
+
+/**
+ * Map `alwaysApply` source field to `inclusion` canonical field.
+ */
+function mapAlwaysApplyToInclusion(
+	sourceFm: Record<string, unknown>,
+	accountant: SourceAccountant,
+): "always" | "auto" | "fileMatch" | "manual" {
+	if (sourceFm.alwaysApply !== undefined) {
+		accountant.mapField("POWER.md", "alwaysApply", "inclusion", true);
+		return sourceFm.alwaysApply === true ? "always" : "manual";
+	}
+	if (sourceFm.inclusion !== undefined) {
+		accountant.mapField("POWER.md", "inclusion", "inclusion", false);
+		const val = String(sourceFm.inclusion);
+		if (
+			val === "always" ||
+			val === "auto" ||
+			val === "fileMatch" ||
+			val === "manual"
+		) {
+			return val;
+		}
+	}
+	return "manual";
+}

package/src/rosetta/builtins/sources/kiro-skill.ts

@@ -0,0 +1,230 @@
+/**
+ * Rosetta Stone — Kiro Skill Source Translator
+ *
+ * Pure translator for the `kiro-skill` format:
+ * - Consumes `SKILL.md` → extracts frontmatter (name, description, keywords) and body
+ * - Consumes `references/*.md` files → maps to workflows
+ * - Preserves any other files found
+ * - Sets `type: "skill"`, `harnesses: ["kiro"]`
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 2.9, 4.1, 4.2, 4.3, 4.5, 13.7, 14.3
+ */
+
+import matter from "gray-matter";
+
+import type {
+	KnowledgeArtifact,
+	NormalizedRelativePath,
+	SourceDocument,
+	TranslationDiagnostic,
+} from "../../../schemas";
+import { codePointCompare } from "../../contracts";
+import { createDiagnostic } from "../../diagnostics";
+import type {
+	SourceTranslationOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+import { SourceAccountant } from "../../source-accounting";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Translate a kiro-skill document set into a canonical KnowledgeArtifact candidate.
+ *
+ * Expected documents:
+ * - `SKILL.md` (required): YAML frontmatter + Markdown body
+ * - `references/*.md` (optional): mapped to workflows
+ * - Other files: preserved
+ */
+export function translateKiroSkill(
+	documents: readonly SourceDocument[],
+	context: SourceTranslatorContext,
+): SourceTranslationOutput {
+	const accountant = new SourceAccountant();
+	const diagnostics: TranslationDiagnostic[] = [];
+
+	// Find SKILL.md
+	const skillDoc = documents.find((d) => d.path === "SKILL.md");
+	if (!skillDoc) {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_MISSING_KNOWLEDGE_MD", {
+				formatId: "kiro-skill",
+				message: "SKILL.md not found in the provided document set.",
+				source: { path: "SKILL.md" as NormalizedRelativePath },
+			}),
+		);
+		for (const doc of documents) {
+			accountant.preserve(doc.path);
+		}
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	// Parse SKILL.md frontmatter
+	const rawContent =
+		typeof skillDoc.content === "string"
+			? skillDoc.content
+			: new TextDecoder().decode(skillDoc.content);
+
+	let parsed: matter.GrayMatterFile<string>;
+	try {
+		parsed = matter(rawContent);
+	} catch {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_INVALID_FRONTMATTER", {
+				formatId: "kiro-skill",
+				message: "The frontmatter YAML in SKILL.md could not be parsed.",
+				source: { path: "SKILL.md" as NormalizedRelativePath },
+			}),
+		);
+		for (const doc of documents) {
+			accountant.preserve(doc.path);
+		}
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	accountant.consume("SKILL.md");
+
+	const sourceFm = parsed.data as Record<string, unknown>;
+	const body = parsed.content.trim();
+
+	// Resolve artifact name from caller context or frontmatter
+	const artifactNameHint = context.callerContext?.artifactNameHint as
+		| string
+		| undefined;
+	const name = String(sourceFm.name || artifactNameHint || "unnamed-skill");
+
+	// Map fields
+	accountant.mapField("SKILL.md", "name", "name", false);
+	accountant.mapField("SKILL.md", "description", "description", false);
+	accountant.mapField("SKILL.md", "keywords", "keywords", false);
+
+	// Collect references/ files as workflows
+	const refDocs = documents
+		.filter((d) => d.path.startsWith("references/") && d.path.endsWith(".md"))
+		.sort((a, b) => codePointCompare(a.path, b.path));
+
+	const workflows = refDocs.map((doc) => {
+		accountant.consume(doc.path);
+		const content =
+			typeof doc.content === "string"
+				? doc.content
+				: new TextDecoder().decode(doc.content);
+		const filename = doc.path.slice("references/".length);
+		const name = filename.replace(/\.md$/, "");
+		return { name, filename, content };
+	});
+
+	// Preserve any files that are neither SKILL.md nor in references/
+	for (const doc of documents) {
+		if (doc.path === "SKILL.md") continue;
+		if (doc.path.startsWith("references/") && doc.path.endsWith(".md"))
+			continue;
+		accountant.preserve(doc.path);
+	}
+
+	// Apply defaults
+	const appliedDefaults: Array<{
+		field: string;
+		value: unknown;
+		rule: string;
+	}> = [];
+
+	const displayName = String(sourceFm.displayName || name);
+	if (!sourceFm.displayName) {
+		appliedDefaults.push({
+			field: "displayName",
+			value: displayName,
+			rule: "kiro-skill-default-displayName",
+		});
+	}
+
+	const description = String(sourceFm.description || "");
+	const keywords = Array.isArray(sourceFm.keywords)
+		? sourceFm.keywords.map(String)
+		: [];
+
+	const author = String(sourceFm.author || "");
+	if (!sourceFm.author) {
+		appliedDefaults.push({
+			field: "author",
+			value: "",
+			rule: "kiro-skill-default-author",
+		});
+	}
+
+	const version = String(sourceFm.version || "0.1.0");
+	if (!sourceFm.version) {
+		appliedDefaults.push({
+			field: "version",
+			value: version,
+			rule: "kiro-skill-default-version",
+		});
+	}
+
+	// Emit diagnostics for applied defaults
+	for (const def of appliedDefaults) {
+		accountant.applyDefault(def.field, def.value, def.rule);
+		diagnostics.push(
+			createDiagnostic("RS_DEFAULT_APPLIED", {
+				formatId: "kiro-skill",
+				message: `Default applied for "${def.field}": ${JSON.stringify(def.value)}`,
+				source: { path: "SKILL.md" as NormalizedRelativePath },
+			}),
+		);
+	}
+
+	// Build canonical candidate
+	const candidate: KnowledgeArtifact = {
+		name,
+		frontmatter: {
+			name,
+			displayName,
+			description,
+			keywords,
+			author,
+			version,
+			harnesses: ["kiro"],
+			type: "skill",
+			inclusion: "manual",
+			categories: ["documentation"],
+			ecosystem: [],
+			depends: [],
+			enhances: [],
+			maturity: "stable",
+			trust: "community",
+			audience: "intermediate",
+			"model-assumptions": [],
+			collections: [],
+			"inherit-hooks": false,
+			outcomes: [],
+		},
+		body,
+		hooks: [],
+		mcpServers: [],
+		workflows,
+		sourcePath: "SKILL.md",
+		extraFields: {},
+		bodyOverrides: {},
+	};
+
+	return {
+		candidate,
+		diagnostics,
+		consumedPaths: accountant.getConsumedPaths(),
+		preservedPaths: accountant.getPreservedPaths(),
+	};
+}

package/src/rosetta/builtins/sources/qdeveloper-native.ts

@@ -0,0 +1,181 @@
+/**
+ * Rosetta Stone — Q Developer Harness-Native Source Translator
+ *
+ * Translates Amazon Q Developer's native format
+ * (.qdeveloper/rules/*.md or .amazonq/rules/*.md)
+ * into a canonical KnowledgeArtifact candidate.
+ *
+ * CONSTRAINTS:
+ * - NO filesystem, process, clock, random, Git, or network imports
+ * - Pure function only
+ *
+ * Requirements: 2.9, 4.1, 4.2, 4.3, 4.5, 4.6
+ */
+
+import matter from "gray-matter";
+import type { SourceDocument, TranslationDiagnostic } from "../../../schemas";
+import { createDiagnostic } from "../../diagnostics";
+import type {
+	SourceTranslationOutput,
+	SourceTranslatorContext,
+} from "../../registry";
+import {
+	normalizeDocumentOrder,
+	SourceAccountant,
+} from "../../source-accounting";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Checks if a document is a Q Developer rule file under .qdeveloper/rules/.
+ */
+function isQDeveloperRuleFile(path: string): boolean {
+	return (
+		(path.includes(".qdeveloper/rules/") ||
+			path.includes(".qdeveloper/rules\\")) &&
+		path.endsWith(".md")
+	);
+}
+
+/**
+ * Checks if a document is a Q Developer rule file under .amazonq/rules/.
+ */
+function isAmazonQRuleFile(path: string): boolean {
+	return (
+		(path.includes(".amazonq/rules/") || path.includes(".amazonq/rules\\")) &&
+		path.endsWith(".md")
+	);
+}
+
+/**
+ * Checks if a document is any recognized Q Developer file.
+ */
+function isQDeveloperFile(path: string): boolean {
+	return isQDeveloperRuleFile(path) || isAmazonQRuleFile(path);
+}
+
+/**
+ * Derives a kebab-case artifact name from a document path.
+ */
+function deriveArtifactName(path: string): string {
+	const segments = path.split("/");
+	const base = segments[segments.length - 1] ?? "";
+	const name = base.replace(/\.[^.]+$/, "");
+	return name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Exported Translator
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Q Developer harness-native source translator.
+ *
+ * Consumes:
+ * - .qdeveloper/rules/*.md → rule file body content
+ * - .amazonq/rules/*.md → rule file body content (legacy path)
+ *
+ * Sets type: "rule" and harnesses: ["qdeveloper"]
+ */
+export function translateQDeveloperNative(
+	documents: readonly SourceDocument[],
+	context: SourceTranslatorContext,
+): SourceTranslationOutput {
+	const accountant = new SourceAccountant();
+	const diagnostics: TranslationDiagnostic[] = [];
+	const sorted = normalizeDocumentOrder(documents);
+
+	// Determine artifact name from caller context
+	const artifactNameHint = context.callerContext.artifactNameHint as
+		| string
+		| undefined;
+
+	// Classify documents — prefer .qdeveloper/rules/, fall back to .amazonq/rules/
+	const qdeveloperDocs = sorted.filter((d) => isQDeveloperRuleFile(d.path));
+	const amazonqDocs = sorted.filter((d) => isAmazonQRuleFile(d.path));
+
+	const primaryDoc = qdeveloperDocs[0] ?? amazonqDocs[0];
+
+	// Handle missing primary file
+	if (!primaryDoc) {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_MISSING_KNOWLEDGE_MD", {
+				formatId: context.format.id,
+				message:
+					"No .qdeveloper/rules/ or .amazonq/rules/ file found in the document set.",
+			}),
+		);
+		return {
+			diagnostics,
+			consumedPaths: accountant.getConsumedPaths(),
+			preservedPaths: accountant.getPreservedPaths(),
+		};
+	}
+
+	// Parse primary file
+	const content =
+		typeof primaryDoc.content === "string"
+			? primaryDoc.content
+			: new TextDecoder().decode(primaryDoc.content);
+
+	let frontmatterData: Record<string, unknown> = {};
+	let body = "";
+
+	try {
+		const parsed = matter(content);
+		frontmatterData = { ...parsed.data };
+		body = parsed.content.trim();
+	} catch {
+		diagnostics.push(
+			createDiagnostic("RS_CANONICAL_INVALID_FRONTMATTER", {
+				formatId: context.format.id,
+				message: `Failed to parse frontmatter in "${primaryDoc.path}".`,
+				source: { path: primaryDoc.path },
+			}),
+		);
+		body = content.trim();
+	}
+
+	accountant.consume(primaryDoc.path);
+	accountant.mapField(primaryDoc.path, "content", "body");
+
+	// Mark remaining files as preserved
+	for (const doc of sorted) {
+		if (doc.path !== primaryDoc.path && isQDeveloperFile(doc.path)) {
+			accountant.preserve(doc.path);
+		}
+	}
+
+	// Derive artifact name
+	const name = artifactNameHint ?? deriveArtifactName(primaryDoc.path);
+
+	// Build the canonical candidate
+	const candidate: Record<string, unknown> = {
+		name,
+		frontmatter: {
+			name,
+			...frontmatterData,
+			type: "rule",
+			harnesses: ["qdeveloper"],
+		},
+		body,
+		hooks: [],
+		mcpServers: [],
+		workflows: [],
+		sourcePath: primaryDoc.path,
+		extraFields: {},
+		bodyOverrides: {},
+	};
+
+	return {
+		candidate,
+		diagnostics,
+		consumedPaths: accountant.getConsumedPaths(),
+		preservedPaths: accountant.getPreservedPaths(),
+	};
+}