job-forge 2.14.30 → 2.14.32

package/scripts/facts.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+import { relative } from 'path';
+import {
+  formatBuildResult,
+  formatCheckResult,
+  formatConfigSummary,
+  formatFacts,
+  formatVerifyResult,
+} from '@razroo/iso-facts';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  buildJobForgeFacts,
+  checkJobForgeFacts,
+  factsExist,
+  hasJobForgeFact,
+  jobForgeFactsConfigPath,
+  jobForgeFactsPath,
+  jobForgeFactsSummary,
+  queryJobForgeFacts,
+  readJobForgeFactsConfig,
+  verifyJobForgeFacts,
+} from '../lib/jobforge-facts.mjs';
+
+const USAGE = `job-forge facts - local deterministic fact materialization
+
+Usage:
+  job-forge facts:status [--json]
+  job-forge facts:build [--json]
+  job-forge facts:query [text] [--fact <fact>] [--key <key>] [--value <value>] [--source <path>] [--tag <tag>] [--limit N] [--no-rebuild] [--json]
+  job-forge facts:has [text] [--fact <fact>] [--key <key>] [--value <value>] [--source <path>] [--tag <tag>] [--no-rebuild] [--json]
+  job-forge facts:verify [--no-rebuild] [--json]
+  job-forge facts:check [--no-rebuild] [--json]
+  job-forge facts:explain [--json]
+  job-forge facts:path
+
+Default config is templates/facts.json. Default output is .jobforge-facts.json.
+Query, has, verify, and check rebuild facts by default so consumer projects need
+no manual setup. Use --no-rebuild to inspect the existing fact set only.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(jobForgeFactsPath(PROJECT_DIR));
+  } else if (cmd === 'status') {
+    status(opts);
+  } else if (cmd === 'build') {
+    build(opts);
+  } else if (cmd === 'query') {
+    query(opts);
+  } else if (cmd === 'has') {
+    has(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'check') {
+    check(opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown facts command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const opts = {
+    json: false,
+    help: false,
+    rebuild: true,
+    query: {},
+    text: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--no-rebuild') {
+      opts.rebuild = false;
+    } else if (arg === '--rebuild') {
+      opts.rebuild = true;
+    } else if (arg === '--fact') {
+      opts.query.fact = valueAfter(args, ++i, '--fact');
+    } else if (arg.startsWith('--fact=')) {
+      opts.query.fact = arg.slice('--fact='.length);
+    } else if (arg === '--key') {
+      opts.query.key = valueAfter(args, ++i, '--key');
+    } else if (arg.startsWith('--key=')) {
+      opts.query.key = arg.slice('--key='.length);
+    } else if (arg === '--value') {
+      opts.query.value = valueAfter(args, ++i, '--value');
+    } else if (arg.startsWith('--value=')) {
+      opts.query.value = arg.slice('--value='.length);
+    } else if (arg === '--source') {
+      opts.query.source = valueAfter(args, ++i, '--source');
+    } else if (arg.startsWith('--source=')) {
+      opts.query.source = arg.slice('--source='.length);
+    } else if (arg === '--tag') {
+      opts.query.tag = valueAfter(args, ++i, '--tag');
+    } else if (arg.startsWith('--tag=')) {
+      opts.query.tag = arg.slice('--tag='.length);
+    } else if (arg === '--limit') {
+      opts.query.limit = parsePositiveInteger(valueAfter(args, ++i, '--limit'), '--limit');
+    } else if (arg.startsWith('--limit=')) {
+      opts.query.limit = parsePositiveInteger(arg.slice('--limit='.length), '--limit');
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown flag "${arg}"`);
+    } else {
+      opts.text.push(arg);
+    }
+  }
+
+  if (opts.text.length > 0) opts.query.text = opts.text.join(' ');
+  return opts;
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parsePositiveInteger(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive integer`);
+  return parsed;
+}
+
+function status(opts) {
+  const summary = jobForgeFactsSummary(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  if (!summary.exists) {
+    console.log(`facts: missing (${relativePath(summary.path)})`);
+    console.log('run: job-forge facts:build');
+    return;
+  }
+  const result = verifyJobForgeFacts({ rebuild: false }, PROJECT_DIR);
+  console.log(`facts:   ${relativePath(summary.path)}`);
+  console.log(`config:  ${relativePath(summary.config)}`);
+  console.log(`sources: ${summary.sources}`);
+  console.log(`files:   ${summary.files}`);
+  console.log(`facts:   ${summary.facts}`);
+  console.log(`verify:  ${result.ok ? 'PASS' : 'FAIL'} (${result.issues.length} issue(s))`);
+}
+
+function build(opts) {
+  const { factSet, out } = buildJobForgeFacts({}, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify({ out, stats: factSet.stats }, null, 2));
+    return;
+  }
+  console.log(formatBuildResult(factSet, out));
+}
+
+function query(opts) {
+  const facts = queryJobForgeFacts(opts.query, { rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(facts, null, 2));
+    return;
+  }
+  console.log(formatFacts(facts));
+}
+
+function has(opts) {
+  const hit = hasJobForgeFact(opts.query, { rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify({ hit, query: opts.query }, null, 2));
+  } else {
+    console.log(hit ? 'MATCH' : 'MISS');
+  }
+  process.exit(hit ? 0 : 1);
+}
+
+function verify(opts) {
+  if (!opts.rebuild && !factsExist(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeFactsPath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`facts: missing (${relativePath(jobForgeFactsPath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = verifyJobForgeFacts({ rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function check(opts) {
+  if (!opts.rebuild && !factsExist(PROJECT_DIR)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: true, missing: true, path: jobForgeFactsPath(PROJECT_DIR) }, null, 2));
+    } else {
+      console.log(`facts: missing (${relativePath(jobForgeFactsPath(PROJECT_DIR))})`);
+    }
+    return;
+  }
+  const result = checkJobForgeFacts({ rebuild: opts.rebuild }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatCheckResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function explain(opts) {
+  const config = readJobForgeFactsConfig(PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+  console.log(`config: ${relativePath(jobForgeFactsConfigPath(PROJECT_DIR))}`);
+  console.log(formatConfigSummary(config));
+}
+
+function relativePath(path) {
+  return relative(PROJECT_DIR, path) || '.';
+}

package/scripts/score.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+import { writeFileSync } from 'fs';
+import { relative, resolve } from 'path';
+import {
+  formatCheckResult,
+  formatComparison,
+  formatConfigSummary,
+  formatGateResult,
+  formatScoreResult,
+  formatVerifyResult,
+} from '@razroo/iso-score';
+import { PROJECT_DIR } from '../tracker-lib.mjs';
+import {
+  checkJobForgeScore,
+  compareJobForgeScores,
+  computeJobForgeScore,
+  evaluateJobForgeScoreGate,
+  jobForgeScoreConfigPath,
+  readJobForgeScoreConfig,
+  readJsonFile,
+  verifyJobForgeScoreResult,
+} from '../lib/jobforge-score.mjs';
+
+const USAGE = `job-forge score - deterministic JobForge offer scoring
+
+Usage:
+  job-forge score:compute --input <file> [--out <file>] [--profile jobforge] [--json]
+  job-forge score:check --input <file> [--profile jobforge] [--json]
+  job-forge score:gate --input <file> [--gate apply] [--profile jobforge] [--json]
+  job-forge score:verify --score <file> [--json]
+  job-forge score:compare --left <file> --right <file> [--profile jobforge] [--json]
+  job-forge score:explain [--profile jobforge] [--json]
+  job-forge score:path
+
+Default config is templates/score.json. The input may be native iso-score
+JSON or JobForge's existing report score JSON shape with a top-level scores map.`;
+
+const [cmd = 'help', ...rawArgs] = process.argv.slice(2);
+const opts = parseArgs(rawArgs);
+
+if (opts.help || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(USAGE);
+  process.exit(0);
+}
+
+try {
+  if (cmd === 'path') {
+    console.log(jobForgeScoreConfigPath(PROJECT_DIR));
+  } else if (cmd === 'compute') {
+    compute(opts);
+  } else if (cmd === 'check') {
+    check(opts);
+  } else if (cmd === 'gate') {
+    gate(opts);
+  } else if (cmd === 'verify') {
+    verify(opts);
+  } else if (cmd === 'compare') {
+    compare(opts);
+  } else if (cmd === 'explain') {
+    explain(opts);
+  } else {
+    console.error(`unknown score command "${cmd}"\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(args) {
+  const opts = {
+    json: false,
+    help: false,
+    profile: '',
+    gate: '',
+    input: '',
+    score: '',
+    left: '',
+    right: '',
+    out: '',
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--profile') {
+      opts.profile = valueAfter(args, ++i, '--profile');
+    } else if (arg.startsWith('--profile=')) {
+      opts.profile = arg.slice('--profile='.length);
+    } else if (arg === '--gate') {
+      opts.gate = valueAfter(args, ++i, '--gate');
+    } else if (arg.startsWith('--gate=')) {
+      opts.gate = arg.slice('--gate='.length);
+    } else if (arg === '--input') {
+      opts.input = valueAfter(args, ++i, '--input');
+    } else if (arg.startsWith('--input=')) {
+      opts.input = arg.slice('--input='.length);
+    } else if (arg === '--score') {
+      opts.score = valueAfter(args, ++i, '--score');
+    } else if (arg.startsWith('--score=')) {
+      opts.score = arg.slice('--score='.length);
+    } else if (arg === '--left') {
+      opts.left = valueAfter(args, ++i, '--left');
+    } else if (arg.startsWith('--left=')) {
+      opts.left = arg.slice('--left='.length);
+    } else if (arg === '--right') {
+      opts.right = valueAfter(args, ++i, '--right');
+    } else if (arg.startsWith('--right=')) {
+      opts.right = arg.slice('--right='.length);
+    } else if (arg === '--out') {
+      opts.out = valueAfter(args, ++i, '--out');
+    } else if (arg.startsWith('--out=')) {
+      opts.out = arg.slice('--out='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else {
+      throw new Error(`unknown flag "${arg}"`);
+    }
+  }
+
+  return opts;
+}
+
+function valueAfter(values, index, flag) {
+  const value = values[index];
+  if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function compute(opts) {
+  if (!opts.input) throw new Error('score:compute requires --input');
+  const result = computeJobForgeScore(readJsonFile(resolve(opts.input)), { profile: opts.profile }, PROJECT_DIR);
+  if (opts.out) writeFileSync(resolve(opts.out), `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatScoreResult(result));
+  }
+}
+
+function check(opts) {
+  if (!opts.input) throw new Error('score:check requires --input');
+  const result = checkJobForgeScore(readJsonFile(resolve(opts.input)), { profile: opts.profile }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatCheckResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function gate(opts) {
+  if (!opts.input) throw new Error('score:gate requires --input');
+  const result = evaluateJobForgeScoreGate(readJsonFile(resolve(opts.input)), {
+    gate: opts.gate || 'apply',
+    profile: opts.profile,
+  }, PROJECT_DIR);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatGateResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function verify(opts) {
+  if (!opts.score) throw new Error('score:verify requires --score');
+  const result = verifyJobForgeScoreResult(readJsonFile(resolve(opts.score)));
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatVerifyResult(result));
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+function compare(opts) {
+  if (!opts.left) throw new Error('score:compare requires --left');
+  if (!opts.right) throw new Error('score:compare requires --right');
+  const result = compareJobForgeScores(
+    readJsonFile(resolve(opts.left)),
+    readJsonFile(resolve(opts.right)),
+    { profile: opts.profile },
+    PROJECT_DIR,
+  );
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatComparison(result));
+  }
+  const hasErrors = [...result.left.issues, ...result.right.issues].some((issue) => issue.severity === 'error');
+  process.exit(hasErrors ? 1 : 0);
+}
+
+function explain(opts) {
+  const config = readJobForgeScoreConfig(PROJECT_DIR);
+  if (opts.json) {
+    const value = opts.profile
+      ? { ...config, profiles: config.profiles.filter((profile) => profile.name === opts.profile) }
+      : config;
+    console.log(JSON.stringify(value, null, 2));
+  } else {
+    console.log(`config: ${relative(PROJECT_DIR, jobForgeScoreConfigPath(PROJECT_DIR))}`);
+    console.log(formatConfigSummary(config, opts.profile || undefined));
+  }
+}

package/templates/facts.json

@@ -0,0 +1,200 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "name": "reports",
+      "include": ["reports/*.md"],
+      "format": "text",
+      "rules": [
+        {
+          "fact": "job.url",
+          "pattern": "^\\*\\*URL:\\*\\*\\s*(?<url>https?://\\S+)",
+          "flags": "i",
+          "key": "url:{url}",
+          "value": "{url}",
+          "fields": {
+            "url": "{url}",
+            "report": "{source}"
+          },
+          "tags": ["report", "url"]
+        },
+        {
+          "fact": "job.score",
+          "pattern": "^\\*\\*Score:\\*\\*\\s*(?<score>[0-9.]+/5)",
+          "flags": "i",
+          "key": "report:{source}:score",
+          "value": "{score}",
+          "fields": {
+            "score": "{score}",
+            "report": "{source}"
+          },
+          "tags": ["report", "score"]
+        }
+      ]
+    },
+    {
+      "name": "application-day-files",
+      "include": ["data/applications/*.md"],
+      "format": "markdown-table",
+      "records": [
+        {
+          "fact": "application.status",
+          "key": "company-role:{Company|slug}:{Role|slug}",
+          "value": "{Status}",
+          "fields": {
+            "num": "{#}",
+            "date": "{Date}",
+            "company": "{Company}",
+            "role": "{Role}",
+            "score": "{Score}",
+            "status": "{Status}",
+            "pdf": "{PDF}",
+            "report": "{Report}",
+            "notes": "{Notes}"
+          },
+          "tags": ["tracker", "application"]
+        }
+      ]
+    },
+    {
+      "name": "application-single-file",
+      "include": ["data/applications.md", "applications.md"],
+      "format": "markdown-table",
+      "records": [
+        {
+          "fact": "application.status",
+          "key": "company-role:{Company|slug}:{Role|slug}",
+          "value": "{Status}",
+          "fields": {
+            "num": "{#}",
+            "date": "{Date}",
+            "company": "{Company}",
+            "role": "{Role}",
+            "score": "{Score}",
+            "status": "{Status}",
+            "pdf": "{PDF}",
+            "report": "{Report}",
+            "notes": "{Notes}"
+          },
+          "tags": ["tracker", "application"]
+        }
+      ]
+    },
+    {
+      "name": "tracker-additions",
+      "include": ["batch/tracker-additions/*.tsv", "batch/tracker-additions/merged/*.tsv"],
+      "format": "tsv",
+      "header": false,
+      "columns": ["num", "date", "company", "role", "statusOrScore", "scoreOrStatus", "pdf", "report", "notes"],
+      "records": [
+        {
+          "fact": "tracker.addition",
+          "key": "company-role:{company|slug}:{role|slug}",
+          "value": "{source}",
+          "fields": ["num", "date", "company", "role", "statusOrScore", "scoreOrStatus", "pdf", "report", "notes"],
+          "tags": ["tracker", "tsv"]
+        }
+      ]
+    },
+    {
+      "name": "pipeline",
+      "include": ["data/pipeline.md"],
+      "format": "text",
+      "rules": [
+        {
+          "fact": "job.url",
+          "pattern": "^\\s*-\\s*\\[(?<state>[ xX])\\]\\s+(?<url>https?://\\S+)",
+          "key": "url:{url}",
+          "value": "{state}",
+          "fields": {
+            "url": "{url}",
+            "state": "{state}",
+            "pipeline": "{source}"
+          },
+          "tags": ["pipeline", "url"]
+        }
+      ]
+    },
+    {
+      "name": "scan-history",
+      "include": ["data/scan-history.tsv"],
+      "format": "tsv",
+      "records": [
+        {
+          "fact": "job.url",
+          "key": "url:{url}",
+          "value": "{url}",
+          "fields": ["date", "company", "role", "url", "ats"],
+          "tags": ["scan", "url"]
+        }
+      ]
+    },
+    {
+      "name": "preflight-candidates-object",
+      "include": ["batch/preflight-candidates.json"],
+      "format": "json",
+      "records": [
+        {
+          "fact": "candidate.ready",
+          "path": "$.candidates[]",
+          "key": "{companyRoleKey}",
+          "value": "{url}",
+          "fields": {
+            "id": "{id}",
+            "company": "{company}",
+            "role": "{role}",
+            "companyRoleKey": "{companyRoleKey}",
+            "url": "{url}",
+            "score": "{score}",
+            "gateStatus": "{gate.status}",
+            "locationStatus": "{location.status}"
+          },
+          "tags": ["candidate", "preflight"]
+        }
+      ]
+    },
+    {
+      "name": "preflight-candidates-array",
+      "include": ["batch/preflight-candidates.json"],
+      "format": "json",
+      "records": [
+        {
+          "fact": "candidate.ready",
+          "path": "$[]",
+          "key": "{companyRoleKey}",
+          "value": "{url}",
+          "fields": {
+            "id": "{id}",
+            "company": "{company}",
+            "role": "{role}",
+            "companyRoleKey": "{companyRoleKey}",
+            "url": "{url}",
+            "score": "{score}",
+            "gateStatus": "{gate.status}",
+            "locationStatus": "{location.status}"
+          },
+          "tags": ["candidate", "preflight"]
+        }
+      ]
+    },
+    {
+      "name": "ledger",
+      "include": [".jobforge-ledger/*.jsonl"],
+      "format": "jsonl",
+      "records": [
+        {
+          "fact": "ledger.event",
+          "key": "{key}",
+          "value": "{type}",
+          "fields": {
+            "type": "{type}",
+            "key": "{key}",
+            "status": "{data.status}",
+            "source": "{source}"
+          },
+          "tags": ["ledger"]
+        }
+      ]
+    }
+  ]
+}

package/templates/migrations.json

@@ -33,6 +33,19 @@
             "index:has": "job-forge index:has",
             "index:query": "job-forge index:query",
             "index:explain": "job-forge index:explain",
+            "facts:build": "job-forge facts:build",
+            "facts:status": "job-forge facts:status",
+            "facts:verify": "job-forge facts:verify",
+            "facts:check": "job-forge facts:check",
+            "facts:has": "job-forge facts:has",
+            "facts:query": "job-forge facts:query",
+            "facts:explain": "job-forge facts:explain",
+            "score:compute": "job-forge score:compute",
+            "score:verify": "job-forge score:verify",
+            "score:check": "job-forge score:check",
+            "score:gate": "job-forge score:gate",
+            "score:compare": "job-forge score:compare",
+            "score:explain": "job-forge score:explain",
             "canon:normalize": "job-forge canon:normalize",
             "canon:key": "job-forge canon:key",
             "canon:compare": "job-forge canon:compare",
@@ -69,6 +82,7 @@
             ".jobforge-ledger/",
             ".jobforge-cache/",
             ".jobforge-index.json",
+            ".jobforge-facts.json",
             ".jobforge-redacted/",
             "batch/preflight-candidates.json",
             "batch/preflight-plan.json",