artifacts

package
v4.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CLIDirPlaceholder   = "<cli-dir>"
	RunStatePlaceholder = "<runstate>"
)
View Source 
const (
	PIILedgerFilename   = ".printing-press-pii-polish.json"
	PIILedgerStaleAfter = 24 * time.Hour
	PIIStatusAccepted   = "accepted"

	// Caps for the punt-pattern gates. The 5 cluster cap matches
	// tools-audit; the 10 baseline floor for all-accepted-no-fixes is
	// large enough that small genuinely-clean runs (which legitimately
	// accept everything) don't trip it.
	PIIDuplicateRationaleThreshold = 5
	PIIAllAcceptedNoFixesThreshold = 10
)
View Source 
const (
	PIIKindCardLast4     = "card-last-4"
	PIIKindOrderID       = "order-id"
	PIIKindASIN          = "asin"
	PIIKindEmail         = "email"
	PIIKindPhoneUS       = "phone-us"
	PIIKindZipPlus4      = "zip-plus-4"
	PIIKindPostalAddress = "postal-address"
)

Finding kinds. These appear in the JSON output and the ledger; changing a value is a backward-incompatible ledger format change.

View Source 
const (
	PIICategoryAttribution          = "attribution"
	PIICategoryPlaceName            = "place_name"
	PIICategoryCorporateName        = "corporate_name"
	PIICategoryDocumentationExample = "documentation_example"
	PIICategoryAPIProviderData      = "api_provider_data"
	PIICategorySyntheticPlaceholder = "synthetic_placeholder"
	PIICategoryOther                = "other"
)

Categories the agent picks from when accepting a finding. The closed enum forces the agent to name the shape of non-PII; freeform reasoning goes in Note.

View Source 
const PIIRedactedSentinel = "<redacted>"

PIIRedactedSentinel is the stable marker used when artifact text is scrubbed before it can be persisted.

View Source 
const ToolsPolishLedgerFilename = ".printing-press-tools-polish.json"

ToolsPolishLedgerFilename is the tools-audit polish ledger basename. Exported here (not in cli) to break the cli → artifacts cycle that would otherwise force tools_audit.go to import its own package.

Variables

This section is empty.

Functions

func CleanupGeneratedCLI 

func CleanupGeneratedCLI(dir string, opts CleanupOptions) error

CleanupGeneratedCLI removes reproducible artifacts from a generated CLI tree.

func FormatPIIFindings added in v4.3.0 

func FormatPIIFindings(findings []PIIFinding) string

func FormatPIIGateFailures added in v4.3.0 

func FormatPIIGateFailures(c PIICompletionStatus) string

func FormatVendorPrefixSecretFindings added in v4.3.0 

func FormatVendorPrefixSecretFindings(findings []VendorPrefixSecretFinding) string

func IsStalePIILedger added in v4.3.0 

func IsStalePIILedger(l *PIILedger) bool

IsStalePIILedger reports whether a ledger's timestamp is older than the staleness window. Callers (audit, gates) decide what to do — typically warn but continue using the ledger so agent state is not lost on a slow-moving workflow.

func PIIFindingID added in v4.3.0 

func PIIFindingID(f PIIFinding) string

PIIFindingID returns a stable 12-hex-char identifier for the finding. The hash composition is (file, line, kind, normalized matched span) — normalization collapses internal whitespace and lowercases so cosmetic formatting churn doesn't invalidate prior accepts. Line changes still force a fresh ID by design.

func PIIPendingCount added in v4.3.0 

func PIIPendingCount(findings []PIIFinding) int

func RedactArchivedSpecSecrets 

func RedactArchivedSpecSecrets(data []byte) []byte

RedactArchivedSpecSecrets removes credential-shaped examples from archived specs while keeping surrounding auth documentation intact.

func RedactCLIDirRoot added in v4.5.1 

func RedactCLIDirRoot(cliDir string) string

RedactCLIDirRoot preserves the slug (basename) so existing consumers that call filepath.Base still get a useful display name.

func RedactPIIJSONKeys added in v4.13.1 

func RedactPIIJSONKeys(text string) (string, bool)

RedactPIIJSONKeys redacts values whose JSON keys commonly carry customer PII. It intentionally skips regex value sweeps so callers can apply it to larger captures before truncating, then run RedactPIIText on the bounded persisted sample.

func RedactPIIText added in v4.13.1 

func RedactPIIText(text string) string

RedactPIIText returns text with customer-PII shapes replaced before the text is written to durable artifacts. JSON input preserves non-PII fields when redactions are needed and returns the original text unchanged when no PII is found.

func RedactPathUnderCLI added in v4.5.1 

func RedactPathUnderCLI(cliDir, p string) string

RedactPathUnderCLI strips $HOME prefixes before the value reaches a committed artifact, falling back to <runstate>/<basename> when p lives outside cliDir.

func WritePIILedger added in v4.3.0 

func WritePIILedger(cliDir string, ledger *PIILedger) error

WritePIILedger serializes the ledger and writes it atomically via temp file + rename. A crash mid-write leaves the previous ledger intact instead of producing a partial file that ReadPIILedger would silently delete, losing accumulated agent state.

Types

type CleanupOptions 

type CleanupOptions struct {
	RemoveCache              bool
	RemoveRuntimeBinary      bool
	RemoveValidationBinaries bool
	RemoveDogfoodBinaries    bool
	RemoveRecursiveCopies    bool
	RemoveFinderMetadata     bool
}

CleanupOptions controls which generated artifacts to remove.

type PIIAllAcceptedIssue added in v4.3.0 

type PIIAllAcceptedIssue struct {
	Baseline int
	Current  int
	Accepted int
}

type PIIAuditOptions added in v4.13.1 

type PIIAuditOptions struct {
	ManuscriptsDir string
}

PIIAuditOptions controls optional scan inputs outside the printed CLI tree.

type PIIAuditResult added in v4.3.0 

type PIIAuditResult struct {
	Findings   []PIIFinding
	Delta      PIILedgerDelta
	Completion PIICompletionStatus
}

func RunPIIAudit added in v4.3.0 

func RunPIIAudit(dir string) (PIIAuditResult, error)

RunPIIAudit performs a full audit cycle against dir: scan with all detectors, reconcile with prior ledger (carrying agent state forward), write the new ledger, and evaluate enforcement primitives. Shared by the pii-audit subcommand (non-JSON path) and the promote/publish gates.

The ledger write is best-effort — if it fails (read-only directory, disk full), the audit result is still returned and a warning is logged to stderr. The gate decision uses the in-memory result.

func RunPIIAuditWithOptions added in v4.13.1 

func RunPIIAuditWithOptions(dir string, opts PIIAuditOptions) (PIIAuditResult, error)

RunPIIAuditWithOptions performs a full audit cycle with optional external scan inputs and persists the reconciled ledger.

func ScanPII added in v4.3.0 

func ScanPII(dir string) (PIIAuditResult, error)

ScanPII performs the audit without writing the ledger. The pii-audit CLI's --json path uses this so a read-only probe doesn't have the side effect of touching the filesystem.

func ScanPIIWithOptions added in v4.13.1 

func ScanPIIWithOptions(dir string, opts PIIAuditOptions) (PIIAuditResult, error)

ScanPIIWithOptions performs the audit without writing the ledger.

type PIICompletionStatus added in v4.3.0 

type PIICompletionStatus struct {
	IncompleteAccepts        []PIIFinding         // accepts that fail missingPIIAcceptFields — see that helper for the full predicate
	DuplicateRationaleGroups []PIIRationaleGroup  // accepts sharing a normalized note
	AllAcceptedNoFixes       *PIIAllAcceptedIssue // every finding accepted, zero fixes from baseline
	NextPending              *PIIFinding          // resume hint
}

Gate fields all empty + no pending findings means the run is complete.

func EvaluatePIICompletion added in v4.3.0 

func EvaluatePIICompletion(findings []PIIFinding, previous *PIILedger) PIICompletionStatus

func (PIICompletionStatus) GateFailureCount added in v4.3.0 

func (c PIICompletionStatus) GateFailureCount() int

GateFailureCount returns the number of gates surfacing an issue the agent must act on. NextPending is a resume hint, not a gate, and is excluded.

func (PIICompletionStatus) HasGateFailure added in v4.3.0 

func (c PIICompletionStatus) HasGateFailure() bool

HasGateFailure is the boolean form of GateFailureCount. Both are used: HasGateFailure for branching, GateFailureCount for the integer in error messages.

type PIIFinding added in v4.3.0 

type PIIFinding struct {
	Kind        string `json:"kind"`
	File        string `json:"file"`
	Line        int    `json:"line"`
	Column      int    `json:"column"`
	MatchedSpan string `json:"matched_span"`

	Status          string `json:"status,omitempty"`
	Note            string `json:"note,omitempty"`
	Category        string `json:"category,omitempty"`
	EvidenceContext string `json:"evidence_context,omitempty"`
}

PIIFinding is one mechanical detection. Status/Note/Category/ EvidenceContext are agent-written ledger fields preserved across re-runs when the identity key (file, line, kind, normalized span) matches.

func FindPII added in v4.3.0 

func FindPII(root string) ([]PIIFinding, error)

FindPII walks root, applies the file-scoping rules, and returns all PII-shape matches. Ordering is stable (file, line, column, kind) so the JSON output and ledger reconcile cleanly across runs.

Per-file scan errors (unreadable file, permission denied) are logged to stderr and skipped — a single bad file does not abort the gate.

func FindPIIWithOptions added in v4.13.1 

func FindPIIWithOptions(root string, opts PIIAuditOptions) ([]PIIFinding, error)

FindPIIWithOptions walks root plus any explicitly supplied external manuscript run inputs. External manuscript findings are reported using the same .manuscripts/<run-id>/... paths that publish package later stages.

type PIILedger added in v4.3.0 

type PIILedger struct {
	Timestamp           time.Time    `json:"timestamp"`
	CLIDir              string       `json:"cli_dir"`
	Findings            []PIIFinding `json:"findings"`
	FindingsCountBefore int          `json:"findings_count_before"`
	Progress            *PIIProgress `json:"progress,omitempty"`
}

PIILedger is the on-disk snapshot of the last PII audit run.

FindingsCountBefore is sticky: captured on the first audit run that finds no existing ledger and preserved across subsequent runs. It anchors the all-accepted-no-fixes gate.

Progress is an optional checkpoint the agent writes after walking each finding. A re-invocation after a context flush reads it to resume mid-walk. When absent, the resume hint is the first pending finding in scan order.

func ReadPIILedger added in v4.3.0 

func ReadPIILedger(cliDir string) *PIILedger

ReadPIILedger loads the ledger at <cliDir>/<PIILedgerFilename>. Returns nil for missing files. Corrupt files are deleted (the data is unrecoverable). Stale ledgers are returned with their content intact — auto-deletion on staleness silently destroyed accumulated agent accepts, so the caller checks IsStalePIILedger to emit a warning rather than erasing the ledger.

type PIILedgerDelta added in v4.3.0 

type PIILedgerDelta struct {
	HasPrevious bool
	Resolved    []PIIFinding // present in previous, absent in current (fixed in source)
	Added       []PIIFinding // present in current, absent in previous
}

func ReconcilePIILedger added in v4.3.0 

func ReconcilePIILedger(previous *PIILedger, current []PIIFinding) PIILedgerDelta

ReconcilePIILedger carries Status/Note/Category/EvidenceContext from the previous ledger onto matching current findings and computes the resolved/added delta in a single pass. Identity is the piiFindingKey (file + line + kind + normalized-span); a finding whose matched span was rewritten in source reads as "old resolved, new added" rather than mutated.

Mutates `current` in place to backfill agent fields.

type PIIProgress added in v4.3.0 

type PIIProgress struct {
	LastProcessedFindingID string `json:"last_processed_finding_id,omitempty"`
}

PIIProgress is the agent-written resume checkpoint.

type PIIRationaleGroup added in v4.3.0 

type PIIRationaleGroup struct {
	Rationale string
	Findings  []PIIFinding
}

type VendorPrefixSecretFinding added in v4.3.0 

type VendorPrefixSecretFinding struct {
	Path string
	Line int
	Kind string
}

func FindPackageSecrets added in v4.10.0 

func FindPackageSecrets(root string, cookieNames []string) ([]VendorPrefixSecretFinding, error)

func FindSpecDeclaredCookieSecrets added in v4.10.0 

func FindSpecDeclaredCookieSecrets(root string, cookieNames []string) ([]VendorPrefixSecretFinding, error)

func FindVendorPrefixSecrets added in v4.3.0 

func FindVendorPrefixSecrets(root string) ([]VendorPrefixSecretFinding, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.