@houserules/payload 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@houserules/payload",
3
- "version": "0.4.2",
3
+ "version": "0.5.0",
4
4
  "description": "houserules: shared payload libraries, copied into .claude/scripts/lib and executed on bare node with zero runtime dependencies.",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -71,11 +71,11 @@
71
71
  "hooks"
72
72
  ],
73
73
  "devDependencies": {
74
- "@types/node": "26.6.5",
74
+ "@types/node": "26.6.6",
75
75
  "publint": "^0.3.25",
76
- "type-fest": "^5.10.0",
76
+ "type-fest": "^6.0.1",
77
77
  "typescript": "^6.0.3",
78
- "vitest": "^5.0.5",
78
+ "vitest": "^5.1.0",
79
79
  "wireit": "^0.15.0",
80
80
  "@houserules/test": "0.1.3"
81
81
  },
@@ -0,0 +1,21 @@
1
+ import type { Finding } from './findings.mjs';
2
+ /** One file argument a checker read, with its full text. */
3
+ export interface CheckerInput {
4
+ path: string;
5
+ text: string;
6
+ }
7
+ /** What `readCheckerInputs` returns: the files it read, and one finding per path it could not. */
8
+ interface CheckerInputs {
9
+ inputs: CheckerInput[];
10
+ unreadable: Finding[];
11
+ }
12
+ /**
13
+ * Reads each file argument a checker was given, in argument order.
14
+ *
15
+ * A path that cannot be read becomes an `error` finding rather than a silent skip, so a clean
16
+ * report means every named file was read. That covers a mistyped path, a directory, and one
17
+ * argument holding several paths joined by spaces. The caller pushes `unreadable` into its
18
+ * report, and the shared exit code does the rest.
19
+ */
20
+ export declare function readCheckerInputs(paths: readonly string[]): CheckerInputs;
21
+ export {};
@@ -0,0 +1,35 @@
1
+ import { readFileSync } from 'node:fs';
2
+ /** The rule id every checker reports an unreadable file argument under. */
3
+ const UNREADABLE_INPUT_RULE = 'checker/unreadable-input';
4
+ function errorCodeOf(error) {
5
+ if (error instanceof Error && 'code' in error)
6
+ return String(error.code);
7
+ return 'unknown error';
8
+ }
9
+ /**
10
+ * Reads each file argument a checker was given, in argument order.
11
+ *
12
+ * A path that cannot be read becomes an `error` finding rather than a silent skip, so a clean
13
+ * report means every named file was read. That covers a mistyped path, a directory, and one
14
+ * argument holding several paths joined by spaces. The caller pushes `unreadable` into its
15
+ * report, and the shared exit code does the rest.
16
+ */
17
+ export function readCheckerInputs(paths) {
18
+ const inputs = [];
19
+ const unreadable = [];
20
+ for (const path of paths) {
21
+ try {
22
+ inputs.push({ path, text: readFileSync(path, 'utf8') });
23
+ }
24
+ catch (error) {
25
+ unreadable.push({
26
+ rule: UNREADABLE_INPUT_RULE,
27
+ level: 'error',
28
+ file: path,
29
+ line: null,
30
+ msg: `Could not read this path (${errorCodeOf(error)}). Pass one existing file per argument.`,
31
+ });
32
+ }
33
+ }
34
+ return { inputs, unreadable };
35
+ }
@@ -1,16 +1,16 @@
1
1
  export interface RunnerBlock {
2
- runner?: string;
3
- filterFlag?: string;
4
- runScriptPrefix?: string[];
5
- commands?: string[];
2
+ runner?: string | undefined;
3
+ filterFlag?: string | undefined;
4
+ runScriptPrefix?: string[] | undefined;
5
+ commands?: string[] | undefined;
6
6
  /** `fix` only: run the fixer when a subagent stops. */
7
- onSubagentStop?: boolean;
7
+ onSubagentStop?: boolean | undefined;
8
8
  /** `fix` only: per-command file extensions, e.g. {"lint:fix": ["ts","tsx"]}. */
9
- commandExtensions?: Record<string, string[]>;
9
+ commandExtensions?: Record<string, string[]> | undefined;
10
10
  /** `verify` only: branch the changed-file diff is taken against. */
11
- baseBranch?: string;
11
+ baseBranch?: string | undefined;
12
12
  /** `verify` only: per-command wall-clock cap in milliseconds. Unset means no cap. */
13
- timeoutMs?: number;
13
+ timeoutMs?: number | undefined;
14
14
  }
15
15
  export interface ConfigTarget {
16
16
  name: string;
@@ -0,0 +1,17 @@
1
+ /** One `### XX-NN` block: its id, its title line, and every `- **key:** value` line by key. */
2
+ export interface ParsedFinding {
3
+ id: string;
4
+ title: string;
5
+ fields: Map<string, string[]>;
6
+ }
7
+ /** Splits a report into its finding blocks, in file order. */
8
+ export declare function parseFindings(text: string): ParsedFinding[];
9
+ /** Every `### XX-NN` finding id in a report, in file order. */
10
+ export declare function findingIds(text: string): string[];
11
+ /**
12
+ * Block defects for one report: missing or invalid fields, destination pairing, evidence,
13
+ * id numbering, and the empty-report statement. Each string names its finding.
14
+ */
15
+ export declare function checkFindings(text: string, destinations: ReadonlySet<string>): string[];
16
+ /** The lines printed per file: a count line, then each defect indented two spaces. */
17
+ export declare function formatFileResult(path: string, findingCount: number, defects: readonly string[]): string;
@@ -0,0 +1,102 @@
1
+ const TAGS = new Set(['quality', 'efficiency']);
2
+ const ACTIONS = new Set(['fix-now', 'adopt', 'backlog', 'park', 'reject']);
3
+ const PHASE_ACTIONS = new Set(['fix-now', 'adopt']);
4
+ const REQUIRED = [
5
+ 'tag',
6
+ 'surface',
7
+ 'evidence',
8
+ 'version gate',
9
+ 'candidate action',
10
+ 'destination',
11
+ 'cost',
12
+ ];
13
+ const FINDING_START = /^### (?=[A-Z]{2}-\d{2} )/m;
14
+ const ID_PREFIX_LENGTH = 'XX-'.length;
15
+ const ID_NUMBER_WIDTH = 2;
16
+ const ID_LENGTH = ID_PREFIX_LENGTH + ID_NUMBER_WIDTH;
17
+ const EVIDENCE_QUOTE_LENGTH = 60;
18
+ /** Splits a report into its finding blocks, in file order. */
19
+ export function parseFindings(text) {
20
+ return text
21
+ .split(FINDING_START)
22
+ .slice(1)
23
+ .map((block) => {
24
+ const fields = new Map();
25
+ for (const match of block.matchAll(/^- \*\*([a-z ]+):\*\* (.*)$/gm)) {
26
+ const key = match[1];
27
+ fields.set(key, [
28
+ ...(fields.get(key) ?? []),
29
+ match[2].trim(),
30
+ ]);
31
+ }
32
+ const titleLine = block.split('\n')[0];
33
+ return {
34
+ id: block.slice(0, ID_LENGTH),
35
+ title: titleLine.slice(ID_LENGTH).trim(),
36
+ fields,
37
+ };
38
+ });
39
+ }
40
+ /** Every `### XX-NN` finding id in a report, in file order. */
41
+ export function findingIds(text) {
42
+ return [...text.matchAll(/^### ([A-Z]{2}-\d{2}) /gm)].map((match) => match[1]);
43
+ }
44
+ function checkActionPairing(id, action, destination, destinations) {
45
+ if (action === undefined || destination === undefined)
46
+ return [];
47
+ if (!ACTIONS.has(action) || !destinations.has(destination))
48
+ return [];
49
+ const namesPhase = destination !== 'none';
50
+ if (PHASE_ACTIONS.has(action) && !namesPhase)
51
+ return [`${id}: ${action} must name a phase, not none`];
52
+ if (!PHASE_ACTIONS.has(action) && namesPhase)
53
+ return [`${id}: ${action} must name none, not ${destination}`];
54
+ return [];
55
+ }
56
+ function checkEvidence(id, lines) {
57
+ return lines
58
+ .filter((line) => !/https?:\/\//.test(line) && !/`[^`]+`/.test(line))
59
+ .map((line) => `${id}: evidence has no URL and no command: ${line.slice(0, EVIDENCE_QUOTE_LENGTH)}`);
60
+ }
61
+ function checkBlock(finding, destinations) {
62
+ const { id, fields } = finding;
63
+ const defects = [];
64
+ for (const key of REQUIRED)
65
+ if (!fields.has(key))
66
+ defects.push(`${id}: missing ${key}`);
67
+ const tag = fields.get('tag')?.[0];
68
+ if (tag !== undefined && !TAGS.has(tag))
69
+ defects.push(`${id}: tag "${tag}"`);
70
+ const action = fields.get('candidate action')?.[0];
71
+ if (action !== undefined && !ACTIONS.has(action))
72
+ defects.push(`${id}: candidate action "${action}"`);
73
+ const destination = fields.get('destination')?.[0];
74
+ if (destination !== undefined && !destinations.has(destination))
75
+ defects.push(`${id}: destination "${destination}"`);
76
+ defects.push(...checkActionPairing(id, action, destination, destinations));
77
+ defects.push(...checkEvidence(id, fields.get('evidence') ?? []));
78
+ return defects;
79
+ }
80
+ /**
81
+ * Block defects for one report: missing or invalid fields, destination pairing, evidence,
82
+ * id numbering, and the empty-report statement. Each string names its finding.
83
+ */
84
+ export function checkFindings(text, destinations) {
85
+ const findings = parseFindings(text);
86
+ const defects = findings.flatMap((finding) => checkBlock(finding, destinations));
87
+ findings.forEach(({ id }, index) => {
88
+ const expected = String(index + 1).padStart(ID_NUMBER_WIDTH, '0');
89
+ if (id.slice(ID_PREFIX_LENGTH) !== expected)
90
+ defects.push(`${id}: numbering gap, expected ${id.slice(0, ID_PREFIX_LENGTH)}${expected}`);
91
+ });
92
+ if (findings.length === 0 && !/zero findings|no findings/i.test(text))
93
+ defects.push('no findings and no statement of why');
94
+ return defects;
95
+ }
96
+ /** The lines printed per file: a count line, then each defect indented two spaces. */
97
+ export function formatFileResult(path, findingCount, defects) {
98
+ return [
99
+ `${path}: ${findingCount} finding(s), ${defects.length} defect(s)`,
100
+ ...defects.map((defect) => ` ${defect}`),
101
+ ].join('\n');
102
+ }
@@ -10,7 +10,7 @@ export interface WorkspacePackage {
10
10
  }
11
11
  /**
12
12
  * Parsed JSON, or null when the file is missing or unparseable. Defaults to
13
- * `PackageJson` because that is the overwhelming caller; pass `T` for the others.
13
+ * `PackageJson` because that is the overwhelming caller. Pass `T` for the others.
14
14
  */
15
15
  export declare function readJson<T = PackageJson>(path: string): T | null;
16
16
  /**
@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
2
2
  import { join, relative } from 'node:path';
3
3
  /**
4
4
  * Parsed JSON, or null when the file is missing or unparseable. Defaults to
5
- * `PackageJson` because that is the overwhelming caller; pass `T` for the others.
5
+ * `PackageJson` because that is the overwhelming caller. Pass `T` for the others.
6
6
  */
7
7
  export function readJson(path) {
8
8
  try {
@@ -132,7 +132,7 @@ function subdirectories(base) {
132
132
  return [];
133
133
  }
134
134
  }
135
- // Recursion cap for `descendants`. No real workspace nests packages this deep; this guards
135
+ // Recursion cap for `descendants`. No real workspace nests packages this deep. This guards
136
136
  // against a symlink loop or a pathological tree rather than encoding a known layout.
137
137
  const MAX_WORKSPACE_DEPTH = 12;
138
138
  /** Every directory at or below `base`, excluding `base` itself. Depth-capped. */