Built by Maven

ai-build-integrity:generate-hashes

Full name:

com.intsof:ai-build-integrity-maven-plugin:0.9.1-SNAPSHOT:generate-hashes

Description:

Generates companion hash files for AI instruction resources (e.g. AGENTS.md, SKILL.md).

This mojo walks a base directory using NIO Files.walkFileTree, finds files matching the configured include globs, and writes a companion hash sidecar file alongside each matched file. The hash captures the file content at build time so that the verify mojo can later detect any unauthorized modifications.

Security rationale: AI agent instructions must not change after the build begins or after the artifact is shipped. Generating hashes at build time creates a tamper-evident seal on all instruction files.

Performance: Uses Files.walkFileTree for a single-pass directory traversal with directory pruning, a 64 KiB streaming hash buffer, and a lookup-table hex encoder. Handles both single-module projects and large multi-module projects efficiently.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is not marked as thread-safe and thus does not support parallel builds.
  • Binds by default to the lifecycle phase: validate.

Optional Parameters

Name Type Since Description
<algorithmBits> int - Hash algorithm bit width. Determines both the algorithm (SHA-256, SHA-384, SHA-512) and the default output extension (.sha256, .sha384, .sha512).
Default: 256
User Property: ai.integrity.algorithm.bits
<baseDir> String - Base directory to scan; defaults to ${project.basedir}.
Default: ${project.basedir}
User Property: ai.integrity.baseDir
<centralHashFile> String - Explicit path to the central hash ledger file. When set, overrides the default target/ai-integrity.<ext> location and enables child modules in a multi-module project to write to the same single shared ledger as the root module.
User Property: ai.integrity.centralHashFile
<excludes> String - Comma-separated glob patterns for files to strictly exclude from hashing.
Default: **/*.sha256,**/*.sha384,**/*.sha512
User Property: ai.integrity.excludes
<executionRootOnly> boolean - If true, the mojo will only execute in the reactor's execution root project.
Default: false
User Property: ai.integrity.executionRootOnly
<forceIncludes> String - Comma-separated glob patterns for files that MUST be processed, bypassing .gitignore rules.
User Property: ai.integrity.forceIncludes
<gitignoreAutoExclude> boolean - If true, natively parse .gitignore files during traversal to auto-exclude paths.
Default: false
User Property: ai.integrity.gitignoreAutoExclude
<hashFileMode> HashFileMode - Strategy for storing generated hashes (SIDECAR or CENTRAL).
Default: SIDECAR
User Property: ai.integrity.hashFileMode
<hideHashFiles> boolean - If true, natively hides the generated hash sidecar files across all operating systems.
Default: true
User Property: ai.integrity.hideHashFiles
<includes> String - Comma-separated glob patterns for resource files to hash (e.g. ** /*.md).
Default: **/*.md
User Property: ai.integrity.includes
<normalizeLineEndings> boolean - If true, Normalizes CRLF to LF in memory before hashing, enabling cross-OS git hashes.
Default: false
User Property: ai.integrity.normalizeLineEndings
<outputExtension> String - Output extension for hash sidecar files. When set to "auto" (the default), the extension is derived from algorithmBits (e.g. .sha256).
Default: auto
User Property: ai.integrity.outputExtension
<skip> boolean - If true, skips the execution of the mojo. Accepts both -Dai.integrity.skip=true and the Maven-conventional -Dskip.ai.integrity=true.
Default: false
User Property: ai.integrity.skip
<skipAlt> boolean - Alternate Maven-conventional skip flag (e.g. -Dskip.ai.integrity=true).
Default: false
User Property: skip.ai.integrity
<skipDirs> String - Comma-separated directory names to skip during traversal (in addition to target).
Default: target,.git,node_modules,.tmp
User Property: ai.integrity.skipDirs
<skipExisting> boolean - If true, skip generating hashes for files that already have a sidecar file.
Default: false
User Property: ai.integrity.skipExisting

Parameter Details

<algorithmBits>

Hash algorithm bit width. Determines both the algorithm (SHA-256, SHA-384, SHA-512) and the default output extension (.sha256, .sha384, .sha512).
  • Type: int
  • Required: No
  • User Property: ai.integrity.algorithm.bits
  • Default: 256

<baseDir>

Base directory to scan; defaults to ${project.basedir}.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.baseDir
  • Default: ${project.basedir}

<centralHashFile>

Explicit path to the central hash ledger file. When set, overrides the default target/ai-integrity.<ext> location and enables child modules in a multi-module project to write to the same single shared ledger as the root module.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.centralHashFile

<excludes>

Comma-separated glob patterns for files to strictly exclude from hashing.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.excludes
  • Default: **/*.sha256,**/*.sha384,**/*.sha512

<executionRootOnly>

If true, the mojo will only execute in the reactor's execution root project.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.executionRootOnly
  • Default: false

<forceIncludes>

Comma-separated glob patterns for files that MUST be processed, bypassing .gitignore rules.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.forceIncludes

<gitignoreAutoExclude>

If true, natively parse .gitignore files during traversal to auto-exclude paths.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.gitignoreAutoExclude
  • Default: false

<hashFileMode>

Strategy for storing generated hashes (SIDECAR or CENTRAL).
  • Type: com.intsof.ai.build.integrity.HashFileMode
  • Required: No
  • User Property: ai.integrity.hashFileMode
  • Default: SIDECAR

<hideHashFiles>

If true, natively hides the generated hash sidecar files across all operating systems.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.hideHashFiles
  • Default: true

<includes>

Comma-separated glob patterns for resource files to hash (e.g. ** /*.md).
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.includes
  • Default: **/*.md

<normalizeLineEndings>

If true, Normalizes CRLF to LF in memory before hashing, enabling cross-OS git hashes.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.normalizeLineEndings
  • Default: false

<outputExtension>

Output extension for hash sidecar files. When set to "auto" (the default), the extension is derived from algorithmBits (e.g. .sha256).
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.outputExtension
  • Default: auto

<skip>

If true, skips the execution of the mojo. Accepts both -Dai.integrity.skip=true and the Maven-conventional -Dskip.ai.integrity=true.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.skip
  • Default: false

<skipAlt>

Alternate Maven-conventional skip flag (e.g. -Dskip.ai.integrity=true).
  • Type: boolean
  • Required: No
  • User Property: skip.ai.integrity
  • Default: false

<skipDirs>

Comma-separated directory names to skip during traversal (in addition to target).
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.skipDirs
  • Default: target,.git,node_modules,.tmp

<skipExisting>

If true, skip generating hashes for files that already have a sidecar file.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.skipExisting
  • Default: false