stylegallery 0.1.0

package/scripts/validate-unity-source-contracts.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { markdownLinkDestinations, structuralMarkdown } from "./markdown-structure.mjs";
+
+const arguments_ = process.argv.slice(2);
+const json = arguments_.includes("--json");
+const rootIndex = arguments_.indexOf("--root");
+const root = rootIndex === -1 ? process.cwd() : path.resolve(arguments_[rootIndex + 1] ?? "");
+const failures = [];
+const documents = [
+  "game-ui/unity/architecture.md",
+  "game-ui/unity/cli-loop.md",
+  "game-ui/unity/org-wiki.md",
+  "game-ui/unity/repository-map.md",
+  "game-ui/unity/ui-systems.md",
+];
+const expectedRevisions = new Map([
+  ["Unity-Technologies/BagelGame", "5d0348bfa013f3c76299dd582c90a7549f66abce"],
+  ["Unity-Technologies/EntityComponentSystemSamples", "6786a741ee1f118ed14cecfa02beae8e926937b0"],
+  ["Unity-Technologies/InputSystem", "8a57d62081cf3546b46444e17223e0121a3568b2"],
+  ["Unity-Technologies/SimpleUIDemo", "c33907f1ffa0f8a30b46f958d3cf45e5da08b01c"],
+  ["Unity-Technologies/UIElementsExamples", "e940d1c9dddfe99fd500c9f34f4801856ad37f18"],
+  ["Unity-Technologies/UIElementsUniteCPH2019RuntimeDemo", "fa4f2c70cf2d6127ab624cc11a2742260ca6ff20"],
+  ["Unity-Technologies/UIElementsUniteLATurretDemo", "1fce133fe3a3473d418066d8005c64340e9985d5"],
+  ["Unity-Technologies/UIToolkitUnityRoyaleRuntimeDemo", "9b5006d2580101b4d08d59d03d7dadc697d75311"],
+  ["Unity-Technologies/UnityCsReference", "79f16640303119112ca5caed4d71c607d0dff6fb"],
+  ["Unity-Technologies/XR-Interaction-Toolkit-Examples", "881f7e197c7b0958621ebd1a05f249bbe254d36f"],
+  ["Unity-Technologies/a11y-public-sample", "ec14cfcb8c10bafab83ea02cd17759d77b225fae"],
+  ["Unity-Technologies/com.unity.uiwidgets", "0310984e947881eca6c2657f1a2fcaaa19329c22"],
+  ["Unity-Technologies/uGUI", "9edb4420267b6652090ece4c28c38bd98746a68e"],
+  ["Unity-Technologies/ui-toolkit-manual-code-examples", "7ed6e7af9fc8a8f83facea818f47928d2e03a30f"],
+  ["Unity-Technologies/unity-industry-viewer-template", "5d50da18f68b14c4dc15bcf3d535878cc2254497"],
+  ["annulusgames/UGUIAnimationSamples", "343c8110e5683be209cc01ccb4cb986175e61643"],
+  ["hatayama/unity-cli-loop", "61a0fe6d7da0aa9d0bcbc6d95944dd069c483ff0"],
+  ["tasharen/ngui", "9bbc56f11e0e25b89fd55b9b9bc67ddf1f182fe2"],
+]);
+
+function read(relative) {
+  const target = path.join(root, relative);
+  if (!fs.existsSync(target)) {
+    failures.push(`${relative}: missing file`);
+    return "";
+  }
+  return fs.readFileSync(target, "utf8");
+}
+
+function frontmatterValue(content, key) {
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---\n/)?.[1] ?? "";
+  return frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim() ?? "";
+}
+
+function validateReviewedOn(relative, content) {
+  const value = frontmatterValue(content, "reviewed_on");
+  const valid = /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`));
+  if (!valid) failures.push(`${relative}: reviewed_on must be an ISO calendar date`);
+}
+
+function validatePinnedLinks(relative, content) {
+  for (const destination of markdownLinkDestinations(content)) {
+    const match = destination.match(/^https:\/\/github\.com\/([^/]+\/[^/]+)\/(?:blob|tree)\/([^/]+)(?:\/|$)/);
+    if (!match) continue;
+    const [, repository, revision] = match;
+    if (!/^[0-9a-f]{40}$/.test(revision) || /^0{40}$/.test(revision)) {
+      failures.push(`${relative}: GitHub body citation must use a non-zero 40-character revision: ${repository}`);
+      continue;
+    }
+    const expected = expectedRevisions.get(repository);
+    if (expected && revision !== expected) failures.push(`${relative}: unexpected pinned revision for ${repository}: ${revision}`);
+  }
+}
+
+function requireIncludes(relative, content, expected, label) {
+  if (!content.includes(expected)) failures.push(`${relative}: missing ${label}`);
+}
+
+for (const relative of documents) {
+  const content = read(relative);
+  if (!content) continue;
+  const body = structuralMarkdown(content);
+  validateReviewedOn(relative, content);
+  validatePinnedLinks(relative, body);
+  requireIncludes(relative, body, "## Source, License, And Attribution", "source attribution section");
+}
+
+const architecture = structuralMarkdown(read("game-ui/unity/architecture.md"));
+requireIncludes("game-ui/unity/architecture.md", architecture, "https://github.com/annulusgames/UGUIAnimationSamples/blob/343c8110e5683be209cc01ccb4cb986175e61643/LICENSE", "pinned sample license");
+
+const cliLoop = structuralMarkdown(read("game-ui/unity/cli-loop.md"));
+requireIncludes("game-ui/unity/cli-loop.md", cliLoop, "https://github.com/hatayama/unity-cli-loop/blob/61a0fe6d7da0aa9d0bcbc6d95944dd069c483ff0/README.md", "pinned adapted source");
+requireIncludes("game-ui/unity/cli-loop.md", cliLoop, "https://github.com/hatayama/unity-cli-loop/blob/61a0fe6d7da0aa9d0bcbc6d95944dd069c483ff0/LICENSE.md", "pinned source license");
+
+const uiSystems = structuralMarkdown(read("game-ui/unity/ui-systems.md"));
+for (const [repository, revision, license] of [
+  ["Unity-Technologies/uGUI", "9edb4420267b6652090ece4c28c38bd98746a68e", "com.unity.ugui/LICENSE.md"],
+  ["Unity-Technologies/UnityCsReference", "79f16640303119112ca5caed4d71c607d0dff6fb", "LICENSE.md"],
+  ["tasharen/ngui", "9bbc56f11e0e25b89fd55b9b9bc67ddf1f182fe2", "License.txt"],
+]) {
+  requireIncludes("game-ui/unity/ui-systems.md", uiSystems, `https://github.com/${repository}/blob/${revision}/${license}`, `pinned license for ${repository}`);
+}
+
+const result = { ok: failures.length === 0, checkedDocuments: documents.length, failures: [...new Set(failures)] };
+if (json) console.log(JSON.stringify(result, null, 2));
+else if (result.ok) console.log(`ok: ${result.checkedDocuments} Unity source contracts`);
+else console.error(result.failures.join("\n"));
+process.exit(result.ok ? 0 : 1);

package/scripts/validate-vocabulary.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = new Set(process.argv.slice(2));
+const json = args.has("--json");
+const root = process.cwd();
+const failures = [];
+const warnings = [];
+
+const glossaryFile = "guides/vocabulary.md";
+const requiredTerms = [
+  "domain",
+  "category",
+  "pattern",
+  "recipe",
+  "gate",
+  "claim",
+  "evidence family",
+  "scroll ownership",
+  "harmony",
+  "debt",
+  "consumer reference",
+  "maturity",
+  "artifact mode",
+];
+
+const requiredIncludes = {
+  [glossaryFile]: [
+    "## Canonical Terms",
+    "## Aliases",
+    "## Deprecated Terms",
+    "## Local-Only Terms",
+    "## Scannability Checklist",
+    "## Vale Proposal",
+    "Prose linting should wait until the vocabulary is stable.",
+    "Local-only: `consumer component`",
+    "In Layout, component implies visual or framework ownership",
+  ],
+};
+
+const recommendedLinks = {
+  "README.md": { target: "guides/vocabulary.md", preferred: "[Controlled vocabulary](guides/vocabulary.md)" },
+  "GUIDE.md": { target: "guides/vocabulary.md", preferred: "[Controlled vocabulary](guides/vocabulary.md)" },
+  "index.md": { target: "guides/vocabulary.md", preferred: "[Controlled vocabulary](guides/vocabulary.md)" },
+  "quality/index.md": { target: "../guides/vocabulary.md", preferred: "[Controlled vocabulary](../guides/vocabulary.md)" },
+};
+
+function read(relative) {
+  const target = path.join(root, relative);
+  if (!fs.existsSync(target)) {
+    failures.push(`${relative}: missing file`);
+    return "";
+  }
+  return fs.readFileSync(target, "utf8");
+}
+
+for (const [relative, snippets] of Object.entries(requiredIncludes)) {
+  const content = read(relative);
+  for (const snippet of snippets) {
+    if (!content.includes(snippet)) failures.push(`${relative}: missing ${snippet}`);
+  }
+}
+
+for (const [relative, link] of Object.entries(recommendedLinks)) {
+  const content = read(relative);
+  if (!content.includes(`](${link.target})`)) failures.push(`${relative}: missing link target ${link.target}`);
+  if (!content.includes(link.preferred)) warnings.push(`${relative}: recommended link label missing ${link.preferred}`);
+}
+
+const glossary = read(glossaryFile);
+const canonicalRecords = [...glossary.matchAll(/^- Canonical: `([^`]+)`\n  - Concept: ([^\n]+)/gm)].map((match) => ({
+  term: match[1].trim(),
+  concept: match[2].trim().toLowerCase(),
+}));
+const canonicalTerms = canonicalRecords.map((record) => record.term);
+
+for (const term of requiredTerms) {
+  if (!canonicalTerms.includes(term)) failures.push(`${glossaryFile}: missing canonical term ${term}`);
+}
+
+const termsSeen = new Set();
+for (const term of canonicalTerms) {
+  if (termsSeen.has(term)) failures.push(`${glossaryFile}: duplicate canonical term ${term}`);
+  termsSeen.add(term);
+}
+
+const conceptToTerm = new Map();
+for (const record of canonicalRecords) {
+  const existing = conceptToTerm.get(record.concept);
+  if (existing && existing !== record.term) {
+    failures.push(`${glossaryFile}: concept "${record.concept}" has multiple canonical terms: ${existing}, ${record.term}`);
+  }
+  conceptToTerm.set(record.concept, record.term);
+}
+
+const result = {
+  ok: failures.length === 0,
+  checkedFiles: [...new Set([...Object.keys(requiredIncludes), ...Object.keys(recommendedLinks)])],
+  requiredTerms,
+  canonicalTerms,
+  failures,
+  warnings,
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`ok: ${canonicalTerms.length} canonical vocabulary terms (${warnings.length} warnings)`);
+} else {
+  console.error(failures.join("\n"));
+}
+
+process.exitCode = result.ok ? 0 : 1;

package/scripts/validate-webpage-workflow.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = new Set(process.argv.slice(2));
+const json = args.has("--json");
+const root = process.cwd();
+const failures = [];
+const warnings = [];
+const contents = new Map();
+
+const requiredIncludes = {
+  "guides/layout-brief.md": [
+    "## Webpage Generation Intake",
+    "Content-to-layout match:",
+    "Harmony evaluation:",
+    "GPT Image reference:",
+    "Required preconditions before prompt:",
+    "Image review extract-vs-ignore:",
+    "Implementation handoff:",
+    "Consumer reference: not_applicable",
+    "Consumer reference reason:",
+    "Accepted image debt:",
+    "## Minimum Required Fields By Use Case",
+    "Homepage:",
+    "Dashboard:",
+    "Article:",
+    "Form:",
+    "Command surface:",
+    "## Rejected Alternatives",
+    "Rejected pattern or recipe:",
+    "Reason rejected:",
+  ],
+  "guides/decision-tree.md": [
+    "Rejected alternatives:",
+  ],
+  "guides/webpage-generation-workflow.md": [
+    "type: Planning Guide",
+    "# Webpage Generation Workflow",
+    "## Use Cases",
+    "## Content-to-Layout Match",
+    "## Harmony Evaluation",
+    "## GPT Image Reference",
+    "Required preconditions before prompt:",
+    "Extract from image:",
+    "Ignore from image:",
+    "## Implementation Handoff",
+    "Implementation debt:",
+    "Final implementation proof:",
+    "Consumer reference: not_applicable",
+    "Consumer reference reason:",
+    "[Consumer Reference Receiver Contract](../consumer-reference/contract.md)",
+    "## Workflow Route Examples",
+    "### Homepage Route",
+    "### Dashboard Route",
+    "### Article Route",
+    "### Form Route",
+    "### Command Surface Route",
+  ],
+  "recipes/homepage.md": [
+    "type: Layout Recipe",
+    "screen_type: Homepage",
+    "## Recommended Pattern Stack",
+    "## Content-To-Layout Matching",
+    "## GPT Image Reference",
+    "Required preconditions before prompt:",
+    "Image review extract-vs-ignore:",
+  ],
+  "quality/gates/harmony-evaluation.md": [
+    "type: Quality Gate",
+    "## Required Contract",
+    "Content-to-layout match:",
+    "Overall harmony:",
+    "GPT Image reference:",
+    "Implementation handoff:",
+    "Rejected alternatives:",
+    "Do not generate a GPT Image reference before harmony evaluation approves the semantic order, section jobs, pattern stack, scroll owner, and constraints.",
+    "Source order, accessibility, brand correctness, and usability cannot be inferred from the image.",
+    "Final implementation proof:",
+  ],
+  "design-engineering/consumer-migration-readiness.md": [
+    "lifecycle: experimental",
+    "provenance_kind: local",
+    "# Consumer Migration Readiness",
+    "## Migration Dimension Contract",
+    "`behavior_inventory`",
+    "`route_parity`",
+    "`field_parity`",
+    "`action_parity`",
+    "`state_transitions`",
+    "`contract_precedence`",
+    "`direct_mutation`",
+    "`indirect_mutation`",
+    "`persistence_round_trip`",
+    "`reset_boundary`",
+    "`exact_time_boundary`",
+    "`defaults_tri_state_mapping`",
+    "`atomic_batch_behavior`",
+    "Consumer migration conformance: declared",
+    "Passing this method does not prove complete accessibility, product correctness, usability, visual quality, independent adoption, cross-browser equivalence, or owner approval.",
+  ],
+  "consumer-reference/contract.md": [
+    "### Migration-Only Extension",
+    "This field is migration-only.",
+    "Do not add it to generic blank handoffs",
+    "Consumer migration conformance: declared",
+  ],
+  "quality/gates/consumer-migration-evidence.md": [
+    "# Consumer Migration Evidence Gate",
+    "## Required Contract",
+    "## Blocking Conditions",
+    "thirteen migration dimensions",
+    "Decision: pass | block",
+  ],
+};
+
+const requiredLinks = {
+  "README.md": { target: "guides/webpage-generation-workflow.md", preferred: "[Webpage Generation Workflow](guides/webpage-generation-workflow.md)" },
+  "GUIDE.md": { target: "guides/webpage-generation-workflow.md", preferred: "[Webpage generation workflow](guides/webpage-generation-workflow.md)" },
+  "recipes/index.md": { target: "homepage.md", preferred: "[Homepage](homepage.md)" },
+  "quality/gates/index.md": { target: "harmony-evaluation.md", preferred: "[Harmony evaluation gate](harmony-evaluation.md)" },
+};
+
+const recommendedIncludes = {
+  "GUIDE.md": [
+    "content-to-layout match",
+    "harmony evaluation",
+    "GPT Image reference",
+    "implementation handoff",
+  ],
+};
+
+const routeSteps = [
+  "Content blocks",
+  "Section jobs",
+  "Recipe",
+  "Pattern stack",
+  "Scroll owner",
+  "Constraints",
+  "Harmony evaluation",
+  "GPT Image reference",
+  "Implementation handoff",
+];
+
+const workflowRoutes = [
+  "Homepage",
+  "Dashboard",
+  "Article",
+  "Form",
+  "Command Surface",
+];
+
+function read(relative) {
+  if (contents.has(relative)) return contents.get(relative);
+  const absolute = path.join(root, relative);
+  if (!fs.existsSync(absolute)) {
+    failures.push(`${relative}: missing file`);
+    contents.set(relative, "");
+    return "";
+  }
+  const content = fs.readFileSync(absolute, "utf8");
+  contents.set(relative, content);
+  return content;
+}
+
+for (const [relative, snippets] of Object.entries(requiredIncludes)) {
+  const content = read(relative);
+  for (const snippet of snippets) {
+    if (!content.includes(snippet)) failures.push(`${relative}: missing ${snippet}`);
+  }
+}
+
+for (const [relative, link] of Object.entries(requiredLinks)) {
+  const content = read(relative);
+  if (!content.includes(`](${link.target})`)) failures.push(`${relative}: missing link target ${link.target}`);
+  if (!content.includes(link.preferred)) warnings.push(`${relative}: recommended link label missing ${link.preferred}`);
+}
+
+for (const [relative, snippets] of Object.entries(recommendedIncludes)) {
+  const content = read(relative);
+  for (const snippet of snippets) {
+    if (!content.includes(snippet)) warnings.push(`${relative}: recommended prose missing ${snippet}`);
+  }
+}
+
+function routeSection(content, route) {
+  const heading = `### ${route} Route`;
+  const start = content.indexOf(heading);
+  if (start === -1) return "";
+  const afterHeading = content.slice(start + heading.length);
+  const nextHeading = afterHeading.search(/\n### /);
+  return nextHeading === -1 ? afterHeading : afterHeading.slice(0, nextHeading);
+}
+
+function requireRouteOrder(relative, route) {
+  const content = read(relative);
+  const section = routeSection(content, route);
+  if (!section) {
+    failures.push(`${relative}: missing ### ${route} Route`);
+    return;
+  }
+
+  const harmonyIndex = section.indexOf("Harmony evaluation");
+  const imageIndex = section.indexOf("GPT Image reference");
+  if (harmonyIndex !== -1 && imageIndex !== -1 && imageIndex < harmonyIndex) {
+    failures.push(`${relative}: route ${route} places GPT Image reference before Harmony evaluation`);
+  }
+
+  let previousIndex = -1;
+  let previousStep = "";
+  for (const step of routeSteps) {
+    const index = section.indexOf(step);
+    if (index === -1) {
+      failures.push(`${relative}: route ${route} missing ${step}`);
+      continue;
+    }
+    if (index < previousIndex) {
+      failures.push(`${relative}: route ${route} places ${step} before ${previousStep}`);
+    }
+    previousIndex = index;
+    previousStep = step;
+  }
+}
+
+for (const route of workflowRoutes) {
+  requireRouteOrder("guides/webpage-generation-workflow.md", route);
+}
+
+for (const relative of ["guides/layout-brief.md", "guides/webpage-generation-workflow.md", "quality/gates/harmony-evaluation.md"]) {
+  if (/^Consumer migration conformance: declared$/m.test(read(relative))) {
+    failures.push(`${relative}: ordinary handoff must not declare consumer migration conformance`);
+  }
+}
+
+const result = {
+  ok: failures.length === 0,
+  checkedFiles: [...new Set([...Object.keys(requiredIncludes), ...Object.keys(requiredLinks), ...Object.keys(recommendedIncludes)])],
+  checkedRequirements: Object.values(requiredIncludes).reduce((total, snippets) => total + snippets.length, 0)
+    + Object.keys(requiredLinks).length
+    + Object.values(recommendedIncludes).reduce((total, snippets) => total + snippets.length, 0),
+  failures,
+  warnings,
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`ok: ${result.checkedRequirements} webpage workflow requirements (${warnings.length} warnings)`);
+} else {
+  console.error(result.failures.join("\n"));
+}
+
+process.exitCode = result.ok ? 0 : 1;

package/scripts/visual-expectation-contract.mjs

@@ -0,0 +1,20 @@
+const environmentFields = Object.freeze([
+  "browser",
+  "browser_revision",
+  "container_image",
+  "platform",
+  "playwright",
+  "viewport",
+]);
+
+function matchesEnvironment(approved, environment) {
+  return environmentFields.every((field) => approved[field] === environment[field]);
+}
+
+export function visualExpectationFor(scenario, environment, approvedEnvironments) {
+  const environments = approvedEnvironments.filter((approved) => matchesEnvironment(approved, environment));
+  if (environments.length !== 1) throw new Error(`capture environment requires exactly one approved visual environment, found ${environments.length}`);
+  const matches = scenario.expected.visual_image.filter((expectation) => expectation.environment_id === environments[0].id);
+  if (matches.length !== 1) throw new Error(`scenario ${scenario.id} requires exactly one approved visual expectation for ${environments[0].id}, found ${matches.length}`);
+  return matches[0];
+}

package/scripts/workflow-action-contract.mjs

@@ -0,0 +1,163 @@
+function indentation(line) {
+  return line.length - line.trimStart().length;
+}
+
+function mappingKeyIndentation(line) {
+  const sequencePrefix = line.match(/^\s*-\s+/);
+  return sequencePrefix ? sequencePrefix[0].length : indentation(line);
+}
+
+function mappingEntry(line) {
+  const match = line.trim().replace(/^-\s+/, "").match(/^(?:([A-Za-z][A-Za-z0-9_-]*)|'([^']*)'|"([^"]*)")\s*:\s*(.*)$/);
+  if (!match) return null;
+  return { key: match[1] ?? match[2] ?? match[3], value: match[4] };
+}
+
+function isMappingHeader(entry, key) {
+  return entry?.key === key && (entry.value === "" || entry.value.startsWith("#"));
+}
+
+function isBlockScalarHeader(value) {
+  return /^[|>](?:[+-]?[1-9]|[1-9]?[+-])?(?:\s+#.*)?$/.test(value);
+}
+
+function structuralLines(lines) {
+  let blockScalarIndentation = null;
+  return lines.map((line) => {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) return line;
+    const lineIndentation = indentation(line);
+    if (blockScalarIndentation !== null && lineIndentation > blockScalarIndentation) return "";
+    blockScalarIndentation = null;
+    const entry = mappingEntry(line);
+    if (entry && isBlockScalarHeader(entry.value)) blockScalarIndentation = lineIndentation;
+    return line;
+  });
+}
+
+function notationFailures(lines, relative) {
+  let actionBlockScalar = false;
+  let anchorsOrAliases = false;
+  let directives = false;
+  let documentMarkers = false;
+  let escapedDoubleQuotedKey = false;
+  let explicitMappingKey = false;
+  let flowCollectionValue = false;
+  let flowSequenceMapping = false;
+  let mergeKey = false;
+  let tags = false;
+  for (const line of lines) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    const lineIndentation = indentation(line);
+    const trimmed = line.trim();
+    const structural = trimmed.replace(/^-\s+/, "");
+    if (lineIndentation === 0 && /^%(?:YAML|TAG)\b/.test(trimmed)) directives = true;
+    if (lineIndentation === 0 && /^(?:---|\.\.\.)(?:\s+#.*)?$/.test(trimmed)) documentMarkers = true;
+    if (/^\?(?:\s|$)/.test(structural)) explicitMappingKey = true;
+    if (/^!\S*(?:\s|$)/.test(structural)) tags = true;
+    if (/^[&*][^\s:[\]{},]+(?:\s|:|$)/.test(structural)) anchorsOrAliases = true;
+    if (/^<<\s*:/.test(structural)) mergeKey = true;
+    const quotedKey = trimmed.match(/^(?:-\s+)?"((?:[^"\\]|\\.)*)"\s*:/)?.[1];
+    if (quotedKey?.includes("\\")) escapedDoubleQuotedKey = true;
+    if (/^-\s*\{/.test(trimmed)) flowSequenceMapping = true;
+    const entry = mappingEntry(line);
+    if (/^[\[{]/.test(entry?.value ?? "") || (!/^-\s*\{/.test(trimmed) && /^[\[{]/.test(structural))) flowCollectionValue = true;
+    if (/^!\S*(?:\s|$)/.test(entry?.value ?? "")) tags = true;
+    if (/^[&*][^\s[\]{},]+(?:\s|$)/.test(entry?.value ?? "")) anchorsOrAliases = true;
+    if (entry?.key === "uses" && isBlockScalarHeader(entry.value)) actionBlockScalar = true;
+  }
+  const failures = [];
+  if (directives) failures.push(`${relative}: YAML directives are forbidden`);
+  if (documentMarkers) failures.push(`${relative}: YAML document markers are forbidden`);
+  if (explicitMappingKey) failures.push(`${relative}: explicit mapping keys are forbidden`);
+  if (tags) failures.push(`${relative}: YAML tags are forbidden`);
+  if (anchorsOrAliases) failures.push(`${relative}: YAML anchors and aliases are forbidden`);
+  if (mergeKey) failures.push(`${relative}: YAML merge keys are forbidden`);
+  if (actionBlockScalar) failures.push(`${relative}: block scalar action refs are forbidden`);
+  if (flowCollectionValue) failures.push(`${relative}: flow-style collection values are forbidden`);
+  if (flowSequenceMapping) failures.push(`${relative}: flow-style sequence mappings are forbidden`);
+  if (escapedDoubleQuotedKey) failures.push(`${relative}: escape sequences in double-quoted mapping keys are forbidden`);
+  return failures;
+}
+
+function directMappingLines(lines, headerIndex, headerIndentation) {
+  const nested = [];
+  for (const line of lines.slice(headerIndex + 1)) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    const lineIndentation = indentation(line);
+    if (lineIndentation <= headerIndentation) break;
+    nested.push({ indentation: lineIndentation, trimmed: line.trim() });
+  }
+  if (nested.length === 0) return [];
+  const directIndentation = Math.min(...nested.map((line) => line.indentation));
+  return nested.filter((line) => line.indentation === directIndentation).map((line) => line.trimmed);
+}
+
+function actionRefFailures(lines, relative) {
+  const failures = [];
+  for (const line of lines) {
+    const entry = mappingEntry(line);
+    if (entry?.key !== "uses") continue;
+    const reference = entry.value.match(/^([^\s#]+)/)?.[1];
+    if (!reference) continue;
+    if (reference.startsWith("./")) continue;
+    if (reference.startsWith("docker://")) {
+      failures.push(`${relative}: docker action refs are forbidden ${line.trim().replace(/^-\s*/, "")}`);
+      continue;
+    }
+    if (!/^[^@\s]+@[a-f0-9]{40}$/i.test(reference)) failures.push(`${relative}: floating or unlabeled action ref ${line.trim().replace(/^-\s*/, "")}`);
+  }
+  return failures;
+}
+
+export function checkoutCredentialFailures(workflow, relative) {
+  const failures = [];
+  const lines = structuralLines(workflow.split("\n"));
+  for (const [index, line] of lines.entries()) {
+    const usesEntry = mappingEntry(line);
+    if (usesEntry?.key !== "uses" || !/^actions\/checkout@/i.test(usesEntry.value)) continue;
+    const usesIndentation = mappingKeyIndentation(line);
+    const withHeaders = [];
+    for (const [offset, following] of lines.slice(index + 1).entries()) {
+      if (following.trim() === "" || following.trimStart().startsWith("#")) continue;
+      const followingIndentation = indentation(following);
+      if (followingIndentation < usesIndentation) break;
+      if (followingIndentation === usesIndentation && isMappingHeader(mappingEntry(following), "with")) withHeaders.push(index + offset + 1);
+    }
+    const entries = withHeaders.length === 1 ? directMappingLines(lines, withHeaders[0], usesIndentation) : [];
+    const credentialEntries = entries.map(mappingEntry).filter((entry) => entry?.key === "persist-credentials");
+    const exactFalse = credentialEntries.length === 1 && /^false(?:\s+#.*)?$/.test(credentialEntries[0].value);
+    if (!exactFalse) failures.push(`${relative}: every actions/checkout step must set persist-credentials: false`);
+  }
+  return failures;
+}
+
+function permissionFailures(lines, relative) {
+  const failures = [];
+  const headers = lines
+    .map((line, index) => ({ entry: mappingEntry(line), index, indentation: indentation(line) }))
+    .filter(({ entry }) => entry?.key === "permissions");
+  if (headers.some((header) => header.indentation > 0)) failures.push(`${relative}: job-level permissions overrides are forbidden`);
+  const topLevel = headers.filter((header) => header.indentation === 0);
+  let exact = topLevel.length === 1 && isMappingHeader(topLevel[0].entry, "permissions");
+  if (exact) {
+    const entries = [];
+    for (const line of lines.slice(topLevel[0].index + 1)) {
+      if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+      if (indentation(line) === 0) break;
+      entries.push(line.trim());
+    }
+    exact = entries.length === 1 && entries[0] === "contents: read";
+  }
+  if (!exact) failures.push(`${relative}: top-level permissions must be exactly contents: read`);
+  return failures;
+}
+
+export function workflowActionFailures(workflow, relative) {
+  const lines = structuralLines(workflow.split("\n"));
+  return [
+    ...notationFailures(lines, relative),
+    ...actionRefFailures(lines, relative),
+    ...checkoutCredentialFailures(workflow, relative),
+    ...permissionFailures(lines, relative),
+  ];
+}