@patronage/factory-ci 0.1.2 → 0.1.3

package/README.md

@@ -12,7 +12,7 @@ It is a **pure library**. There is no `bin`: anything invocable belongs to `psf`
 
 Three repositories independently built the same scaffolding and then drifted: three wordings of the same setup block, the same `@v4` action tags pinned to different commits because they were generated months apart, two esbuild pre-bundles, two Alchemy CLI wrappers, and one disposable-stage grammar invented twice.
 
-The admission rule is **upstream on repetition**: nothing enters this package until it already repeats across at least two projects. Experiments live in one repository first. The public surface is made of three deep modules, not a workflow framework.
+The admission rule is **upstream on repetition**: nothing enters this package until it already repeats across at least two projects. Experiments live in one repository first. The public surface is made of four deep modules, not a workflow framework.
 
 ## Exports
 
@@ -38,8 +38,8 @@ const generated = factoryWorkflow({
   actionFamily: NODE_PNPM_ACTION_FAMILY_NODE24,
   additionalActions: {
     pathsFilter: {
-      tag: "v3",
-      uses: "dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590",
+      tag: "v4.0.2",
+      uses: "dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706",
     },
   },
   generated: {
@@ -59,6 +59,39 @@ workflow({/* caller-owned jobs and topology */}).writeOrLint({
 
 The **runner is not this package's business**. Jobs, runners, permissions, workflow topology, and deploy policy remain with the caller. The returned values are plain structural objects; this package does not depend on gagen.
 
+### Hosted docs-only classification
+
+```ts
+import {
+  hostedDocsOnlyDetectorStep,
+  NODE_PNPM_ACTION_FAMILY_NODE24,
+} from "@patronage/factory-ci";
+import { job, step } from "gagen";
+
+import profile from "../../software-factory.profile.json" with { type: "json" };
+
+const detector = step(
+  hostedDocsOnlyDetectorStep(profile.proof.classificationPolicy)
+);
+
+const changes = job("changes", {
+  runsOn: "ubuntu-latest",
+  steps: [
+    {
+      name: "Checkout",
+      uses: NODE_PNPM_ACTION_FAMILY_NODE24.checkout.uses,
+      with: { "fetch-depth": 0 },
+    },
+    detector,
+  ],
+  outputs: { docs_only: detector.outputs.docs_only },
+});
+```
+
+`hostedDocsOnlyDetectorStep()` takes the consumer's canonical `proof.classificationPolicy` object directly. It emits a small Bash step structurally accepted by gagen, matches the factory classifier's exact-file, prefix, and case-sensitive `.md` semantics, checks both paths of rename and copy records, and forces full CI when `software-factory.profile.json` changes. The package understands the stable classification-policy vocabulary without loading JSON or depending on the rest of the profile schema.
+
+The emitted step needs only checkout, Bash, and Git. It does not install dependencies or invoke `psf`. Missing or zero SHAs, empty diffs, malformed policy, unknown Git change records, and detector errors all leave `docs_only` false (or unset), so the consumer runs full CI. Hosted classification may therefore conservatively run more work when detection fails, but it never carries a second path policy that can drift from the profile.
+
 ### Alchemy entries
 
 ```ts
@@ -89,7 +122,7 @@ The tests pack the actual tarball, extract it into a throwaway external consumer
 
 ## No configuration surface
 
-Functions take plain typed options objects. Proof and preview configuration lives in the canonical `software-factory.profile.json` schema, never in this package (ADR 0021); mapping a profile into these options is the profile's job.
+Functions take plain typed objects. Proof and preview configuration lives in the canonical `software-factory.profile.json` schema, never in this package (ADR 0021); consumers pass the relevant profile policy directly at generation time.
 
 ## Secrets
 

package/dist/index.d.ts

@@ -194,6 +194,30 @@ interface FactoryWorkflowArtifact<Additional extends Readonly<Record<string, Pin
  */
 declare const factoryWorkflow: <const Additional extends Readonly<Record<string, PinnedAction>> = Record<never, never>>(options: FactoryWorkflowOptions<Additional>) => FactoryWorkflowArtifact<Additional>;
 //#endregion
+//#region src/hosted-docs-only-detector.d.ts
+interface HostedDocsOnlyClassificationPolicy {
+  readonly docsOnlyFiles?: readonly string[];
+  readonly docsOnlyMarkdownPrefixes?: readonly string[];
+  readonly docsOnlyPrefixes?: readonly string[];
+}
+interface HostedDocsOnlyDetectorStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<{
+    BASE_SHA: string;
+    HEAD_SHA: string;
+  }>;
+  readonly id: "docs-only";
+  readonly name: "Detect docs-only changes";
+  readonly outputs: readonly ["docs_only"];
+  readonly run: string;
+}
+/**
+ * Generate the pre-install hosted detector from a consumer's canonical
+ * classification policy. The returned object is structurally accepted by
+ * gagen's `step()` without adding a gagen runtime dependency.
+ */
+declare const hostedDocsOnlyDetectorStep: (policy: HostedDocsOnlyClassificationPolicy) => HostedDocsOnlyDetectorStep;
+//#endregion
 //#region src/execute-alchemy-entry.d.ts
 interface ExecuteAlchemyEntryOptions {
   /**
@@ -225,4 +249,4 @@ interface ExecuteAlchemyEntryResult {
  */
 declare const executeAlchemyEntry: (options: ExecuteAlchemyEntryOptions) => Promise<ExecuteAlchemyEntryResult>;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type SetupNodeStepOptions, type WorkflowStep, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, type HostedDocsOnlyClassificationPolicy, type HostedDocsOnlyDetectorStep, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type SetupNodeStepOptions, type WorkflowStep, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, hostedDocsOnlyDetectorStep, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };

package/dist/index.js

@@ -210,6 +210,137 @@ const factoryWorkflow = (options) => {
 	});
 };
 //#endregion
+//#region src/hosted-docs-only-detector.ts
+const githubExpression = (expression) => `\${{ ${expression} }}`;
+const BASE_SHA_EXPRESSION = githubExpression("github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before");
+const HEAD_SHA_EXPRESSION = githubExpression("github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha");
+const stringArray = (value) => {
+	if (value === void 0) return [];
+	if (Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0)) return value;
+};
+const normalizePolicy = (value) => {
+	if (!(value && typeof value === "object" && !Array.isArray(value))) return;
+	const policy = value;
+	const docsOnlyFiles = stringArray(policy.docsOnlyFiles);
+	const docsOnlyMarkdownPrefixes = stringArray(policy.docsOnlyMarkdownPrefixes);
+	const docsOnlyPrefixes = stringArray(policy.docsOnlyPrefixes);
+	if (!(docsOnlyFiles && docsOnlyMarkdownPrefixes && docsOnlyPrefixes)) return;
+	return {
+		docsOnlyFiles,
+		docsOnlyMarkdownPrefixes,
+		docsOnlyPrefixes
+	};
+};
+const shellQuoteSegment = (value) => `'${value.replaceAll("'", String.raw`'\''`)}'`;
+const shellQuote = (value) => value.split("$").map(shellQuoteSegment).join("'$'");
+const shellArray = (values) => `(${values.map(shellQuote).join(" ")})`;
+const shellExpansion = (name) => `\${${name}}`;
+const malformedPolicyScript = String.raw`printf 'docs_only=false\n' >> "$GITHUB_OUTPUT"`;
+const detectorScript = (policy) => String.raw`docs_only=false
+changed_entries_file=""
+
+finish() {
+  detector_status=$?
+  if [ -n "$changed_entries_file" ]; then
+    rm -f "$changed_entries_file" || true
+  fi
+  if [ "$detector_status" -ne 0 ]; then
+    docs_only=false
+  fi
+  printf 'docs_only=%s\n' "$docs_only" >> "$GITHUB_OUTPUT"
+  exit 0
+}
+trap finish EXIT
+set -eo pipefail
+
+if [ -z "$BASE_SHA" ] || [ -z "$HEAD_SHA" ] ||
+  [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ] ||
+  [ "$HEAD_SHA" = "0000000000000000000000000000000000000000" ]; then
+  exit 0
+fi
+
+changed_entries_file="$(mktemp)"
+git diff --name-status -z --find-renames --find-copies-harder \
+  "$BASE_SHA...$HEAD_SHA" -- > "$changed_entries_file"
+if [ ! -s "$changed_entries_file" ]; then
+  exit 0
+fi
+
+docs_only_files=${shellArray(policy.docsOnlyFiles)}
+docs_only_prefixes=${shellArray(policy.docsOnlyPrefixes)}
+docs_only_markdown_prefixes=${shellArray(policy.docsOnlyMarkdownPrefixes)}
+
+is_docs_only_path() {
+  candidate="$1"
+  if [ "$candidate" = "software-factory.profile.json" ]; then
+    return 1
+  fi
+  for policy_path in "${shellExpansion("docs_only_files[@]")}"; do
+    if [ "$candidate" = "$policy_path" ]; then
+      return 0
+    fi
+  done
+  for policy_path in "${shellExpansion("docs_only_prefixes[@]")}"; do
+    if [[ "$candidate" == "$policy_path"* ]]; then
+      return 0
+    fi
+  done
+  if [[ "$candidate" == *.md ]]; then
+    for policy_path in "${shellExpansion("docs_only_markdown_prefixes[@]")}"; do
+      if [[ "$candidate" == "$policy_path"* ]]; then
+        return 0
+      fi
+    done
+  fi
+  return 1
+}
+
+entry_count=0
+while IFS= read -r -d '' change_status <&3; do
+  entry_count=$((entry_count + 1))
+  case "$change_status" in
+    A|D|M)
+      IFS= read -r -d '' changed_path <&3 || exit 0
+      is_docs_only_path "$changed_path" || exit 0
+      ;;
+    R*|C*)
+      if [[ ! "$change_status" =~ ^[RC][0-9]{1,3}$ ]]; then
+        exit 0
+      fi
+      IFS= read -r -d '' source_path <&3 || exit 0
+      IFS= read -r -d '' destination_path <&3 || exit 0
+      is_docs_only_path "$source_path" || exit 0
+      is_docs_only_path "$destination_path" || exit 0
+      ;;
+    *)
+      exit 0
+      ;;
+  esac
+done 3< "$changed_entries_file"
+
+if [ "$entry_count" -gt 0 ]; then
+  docs_only=true
+fi`;
+/**
+* Generate the pre-install hosted detector from a consumer's canonical
+* classification policy. The returned object is structurally accepted by
+* gagen's `step()` without adding a gagen runtime dependency.
+*/
+const hostedDocsOnlyDetectorStep = (policy) => {
+	const normalized = normalizePolicy(policy);
+	return Object.freeze({
+		continueOnError: true,
+		env: Object.freeze({
+			BASE_SHA: BASE_SHA_EXPRESSION,
+			HEAD_SHA: HEAD_SHA_EXPRESSION
+		}),
+		id: "docs-only",
+		name: "Detect docs-only changes",
+		outputs: ["docs_only"],
+		run: normalized ? detectorScript(normalized) : malformedPolicyScript
+	});
+};
+//#endregion
 //#region src/execute-alchemy-entry.ts
 /**
 * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
@@ -241,4 +372,4 @@ const executeAlchemyEntry = async (options) => {
 	};
 };
 //#endregion
-export { NODE_PNPM_ACTION_FAMILY_NODE24, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };
+export { NODE_PNPM_ACTION_FAMILY_NODE24, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, hostedDocsOnlyDetectorStep, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "0.1.2",
-  "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, Alchemy entry execution, and disposable-stage semantics",
+  "version": "0.1.3",
+  "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",
     "cloudflare",

package/src/hosted-docs-only-detector.ts

@@ -0,0 +1,192 @@
+const githubExpression = (expression: string): string =>
+  `\${{ ${expression} }}`;
+
+const BASE_SHA_EXPRESSION = githubExpression(
+  "github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before"
+);
+const HEAD_SHA_EXPRESSION = githubExpression(
+  "github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha"
+);
+
+export interface HostedDocsOnlyClassificationPolicy {
+  readonly docsOnlyFiles?: readonly string[];
+  readonly docsOnlyMarkdownPrefixes?: readonly string[];
+  readonly docsOnlyPrefixes?: readonly string[];
+}
+
+interface NormalizedHostedDocsOnlyClassificationPolicy {
+  readonly docsOnlyFiles: readonly string[];
+  readonly docsOnlyMarkdownPrefixes: readonly string[];
+  readonly docsOnlyPrefixes: readonly string[];
+}
+
+export interface HostedDocsOnlyDetectorStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<{
+    BASE_SHA: string;
+    HEAD_SHA: string;
+  }>;
+  readonly id: "docs-only";
+  readonly name: "Detect docs-only changes";
+  readonly outputs: readonly ["docs_only"];
+  readonly run: string;
+}
+
+const stringArray = (value: unknown): readonly string[] | undefined => {
+  if (value === undefined) {
+    return [];
+  }
+  if (
+    Array.isArray(value) &&
+    value.every((entry) => typeof entry === "string" && entry.length > 0)
+  ) {
+    return value;
+  }
+};
+
+const normalizePolicy = (
+  value: unknown
+): NormalizedHostedDocsOnlyClassificationPolicy | undefined => {
+  if (!(value && typeof value === "object" && !Array.isArray(value))) {
+    return;
+  }
+
+  const policy = value as Record<string, unknown>;
+  const docsOnlyFiles = stringArray(policy.docsOnlyFiles);
+  const docsOnlyMarkdownPrefixes = stringArray(policy.docsOnlyMarkdownPrefixes);
+  const docsOnlyPrefixes = stringArray(policy.docsOnlyPrefixes);
+
+  if (!(docsOnlyFiles && docsOnlyMarkdownPrefixes && docsOnlyPrefixes)) {
+    return;
+  }
+
+  return {
+    docsOnlyFiles,
+    docsOnlyMarkdownPrefixes,
+    docsOnlyPrefixes,
+  };
+};
+
+const shellQuoteSegment = (value: string): string =>
+  `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+const shellQuote = (value: string): string =>
+  value.split("$").map(shellQuoteSegment).join("'$'");
+
+const shellArray = (values: readonly string[]): string =>
+  `(${values.map(shellQuote).join(" ")})`;
+
+const shellExpansion = (name: string): string => `\${${name}}`;
+
+const malformedPolicyScript = String.raw`printf 'docs_only=false\n' >> "$GITHUB_OUTPUT"`;
+
+const detectorScript = (
+  policy: NormalizedHostedDocsOnlyClassificationPolicy
+): string => String.raw`docs_only=false
+changed_entries_file=""
+
+finish() {
+  detector_status=$?
+  if [ -n "$changed_entries_file" ]; then
+    rm -f "$changed_entries_file" || true
+  fi
+  if [ "$detector_status" -ne 0 ]; then
+    docs_only=false
+  fi
+  printf 'docs_only=%s\n' "$docs_only" >> "$GITHUB_OUTPUT"
+  exit 0
+}
+trap finish EXIT
+set -eo pipefail
+
+if [ -z "$BASE_SHA" ] || [ -z "$HEAD_SHA" ] ||
+  [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ] ||
+  [ "$HEAD_SHA" = "0000000000000000000000000000000000000000" ]; then
+  exit 0
+fi
+
+changed_entries_file="$(mktemp)"
+git diff --name-status -z --find-renames --find-copies-harder \
+  "$BASE_SHA...$HEAD_SHA" -- > "$changed_entries_file"
+if [ ! -s "$changed_entries_file" ]; then
+  exit 0
+fi
+
+docs_only_files=${shellArray(policy.docsOnlyFiles)}
+docs_only_prefixes=${shellArray(policy.docsOnlyPrefixes)}
+docs_only_markdown_prefixes=${shellArray(policy.docsOnlyMarkdownPrefixes)}
+
+is_docs_only_path() {
+  candidate="$1"
+  if [ "$candidate" = "software-factory.profile.json" ]; then
+    return 1
+  fi
+  for policy_path in "${shellExpansion("docs_only_files[@]")}"; do
+    if [ "$candidate" = "$policy_path" ]; then
+      return 0
+    fi
+  done
+  for policy_path in "${shellExpansion("docs_only_prefixes[@]")}"; do
+    if [[ "$candidate" == "$policy_path"* ]]; then
+      return 0
+    fi
+  done
+  if [[ "$candidate" == *.md ]]; then
+    for policy_path in "${shellExpansion("docs_only_markdown_prefixes[@]")}"; do
+      if [[ "$candidate" == "$policy_path"* ]]; then
+        return 0
+      fi
+    done
+  fi
+  return 1
+}
+
+entry_count=0
+while IFS= read -r -d '' change_status <&3; do
+  entry_count=$((entry_count + 1))
+  case "$change_status" in
+    A|D|M)
+      IFS= read -r -d '' changed_path <&3 || exit 0
+      is_docs_only_path "$changed_path" || exit 0
+      ;;
+    R*|C*)
+      if [[ ! "$change_status" =~ ^[RC][0-9]{1,3}$ ]]; then
+        exit 0
+      fi
+      IFS= read -r -d '' source_path <&3 || exit 0
+      IFS= read -r -d '' destination_path <&3 || exit 0
+      is_docs_only_path "$source_path" || exit 0
+      is_docs_only_path "$destination_path" || exit 0
+      ;;
+    *)
+      exit 0
+      ;;
+  esac
+done 3< "$changed_entries_file"
+
+if [ "$entry_count" -gt 0 ]; then
+  docs_only=true
+fi`;
+
+/**
+ * Generate the pre-install hosted detector from a consumer's canonical
+ * classification policy. The returned object is structurally accepted by
+ * gagen's `step()` without adding a gagen runtime dependency.
+ */
+export const hostedDocsOnlyDetectorStep = (
+  policy: HostedDocsOnlyClassificationPolicy
+): HostedDocsOnlyDetectorStep => {
+  const normalized = normalizePolicy(policy);
+
+  return Object.freeze({
+    continueOnError: true as const,
+    env: Object.freeze({
+      BASE_SHA: BASE_SHA_EXPRESSION,
+      HEAD_SHA: HEAD_SHA_EXPRESSION,
+    }),
+    id: "docs-only" as const,
+    name: "Detect docs-only changes" as const,
+    outputs: ["docs_only"] as const,
+    run: normalized ? detectorScript(normalized) : malformedPolicyScript,
+  });
+};

package/src/index.ts

@@ -3,9 +3,9 @@
  * repeat across Patronage factory projects (#266, #268).
  *
  * A pure library: no `bin`, no `alchemy` or `effect` dependency, no config
- * surface of its own. Everything takes a plain typed options object; mapping
- * `software-factory.profile.json` into those objects is the profile's job, not
- * this package's (ADR 0021).
+ * surface of its own. Everything takes plain typed values; callers pass
+ * canonical policy from `software-factory.profile.json` without this package
+ * loading or owning that profile (ADR 0021).
  */
 
 export {
@@ -36,6 +36,11 @@ export {
   type SetupNodeStepOptions,
   type WorkflowStep,
 } from "./factory-workflow.ts";
+export {
+  type HostedDocsOnlyClassificationPolicy,
+  type HostedDocsOnlyDetectorStep,
+  hostedDocsOnlyDetectorStep,
+} from "./hosted-docs-only-detector.ts";
 export {
   type ExecuteAlchemyEntryOptions,
   type ExecuteAlchemyEntryResult,