@entrorove/skill 0.1.23 → 0.1.24

package/local-archguard-ast.mjs

@@ -0,0 +1,371 @@
+import ts from 'typescript';
+import { createHash } from 'node:crypto';
+import { analyzeArchguardLanguage, archguardNativeLanguage } from './local-archguard-language-ast.mjs';
+import { analyzeArchguardComponent, archguardComponentLanguage } from './local-archguard-components.mjs';
+
+const LOCKFILES = new Set(['pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock',
+  'bun.lock', 'bun.lockb', 'Cargo.lock', 'go.sum', 'composer.lock', 'Gemfile.lock', 'Pipfile.lock',
+  'poetry.lock', 'uv.lock', 'pdm.lock', 'pubspec.lock', 'packages.lock.json', 'Package.resolved']);
+const THIRD_PARTY = new Set(['node_modules', 'vendor', 'third_party', 'third-party', '.venv', 'site-packages']);
+const SCRIPT_KINDS = new Map([['ts', ts.ScriptKind.TS], ['mts', ts.ScriptKind.TS], ['cts', ts.ScriptKind.TS],
+  ['tsx', ts.ScriptKind.TSX], ['js', ts.ScriptKind.JS], ['mjs', ts.ScriptKind.JS], ['cjs', ts.ScriptKind.JS], ['jsx', ts.ScriptKind.JSX]]);
+const NON_SOURCE_EXTENSIONS = new Set(['txt', 'md', 'markdown', 'json', 'jsonc', 'json5', 'yaml', 'yml',
+  'toml', 'xml', 'ini', 'csv', 'tsv', 'log', 'map', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'ico',
+  'woff', 'woff2', 'ttf', 'otf']);
+const NON_SOURCE_NAMES = new Set(['readme', 'license', 'licence', 'notice', 'changelog', 'authors', 'codeowners',
+  '.gitignore', '.gitattributes', '.editorconfig', '.npmrc', '.yarnrc', '.nvmrc', '.node-version', '.python-version',
+  '.env', '.env.example', '.env.local', '.env.development', '.env.production', '.env.test']);
+const COLOR_PROPERTIES = new Set(['color', 'background', 'backgroundColor', 'border', 'borderColor',
+  'borderTopColor', 'borderRightColor', 'borderBottomColor', 'borderLeftColor', 'fill', 'stroke', 'boxShadow', 'textShadow']);
+const BUILTINS = new Map([
+  ['no-eval', ['security', 'Dynamic code evaluation is forbidden.']],
+  ['no-debug', ['standard', 'Remove debug statements.']],
+  ['no-inline-style', ['standard', 'Use the locked styling system instead of inline style.']],
+  ['no-hardcoded-color', ['standard', 'Use project theme tokens instead of hardcoded colors.']],
+  ['no-magic-number', ['standard', 'Name repeated or domain-significant numeric values.']],
+]);
+function error(code, message) { return Object.assign(new Error(`${code}: ${message}`), { code }); }
+function finding(ruleId, path, message, category = 'architecture', blocking = true, evidence = {}) {
+  return { severity: blocking ? (category === 'architecture' ? 'P0' : 'P1') : 'P2', ruleId,
+    entityRef: path, message, category, blocking, evidence };
+}
+function safePath(path) {
+  return typeof path === 'string' && path.length > 0 && path === path.normalize('NFC') && path === path.trim()
+    && !path.startsWith('/') && !path.startsWith('~') && !/[\\:\u0000-\u001f\u007f]/.test(path)
+    && path.split('/').every(part => part && part !== '.' && part !== '..' && !/[. ]$/.test(part)
+      && !/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\..*)?$/i.test(part));
+}
+function nonSourceFile(path) {
+  const basename = path.split('/').at(-1).toLowerCase();
+  return NON_SOURCE_NAMES.has(basename) || NON_SOURCE_EXTENSIONS.has(basename.split('.').at(-1));
+}
+export function archguardInspectionScope(path, content, audit) {
+  if (!safePath(path)) return 'first-party';
+  const parts = path.split('/'); const directories = parts.slice(0, -1);
+  if (directories.some(part => THIRD_PARTY.has(part))) return 'third-party';
+  if (LOCKFILES.has(parts.at(-1))) return 'dependency-lockfile';
+  const pin = audit?.[`generatedSourcePin:${path}`];
+  if (typeof content === 'string' && typeof pin === 'string' && /^[0-9a-f]{64}$/.test(pin)
+    && pin === createHash('sha256').update(content).digest('hex')) return 'generated';
+  return 'first-party';
+}
+function syntaxKind(pattern) {
+  const kind = Object.hasOwn(ts.SyntaxKind, pattern) ? ts.SyntaxKind[pattern] : undefined;
+  const literals = [ts.SyntaxKind.Identifier, ts.SyntaxKind.PrivateIdentifier, ts.SyntaxKind.NumericLiteral,
+    ts.SyntaxKind.BigIntLiteral, ts.SyntaxKind.StringLiteral, ts.SyntaxKind.NoSubstitutionTemplateLiteral,
+    ts.SyntaxKind.RegularExpressionLiteral];
+  if (typeof kind !== 'number' || /^(?:First|Last|JSDoc)|^(?:Count|SyntaxList|Bundle|Unknown)$/.test(pattern)
+    || (kind < ts.SyntaxKind.FirstNode && !literals.includes(kind))) {
+    throw error('ARCH-AST-SELECTOR-UNSUPPORTED', `Unsupported SyntaxKind selector ${String(pattern)}`);
+  }
+  return kind;
+}
+export function validateArchguardAstRules(rules) {
+  if (!Array.isArray(rules)) throw error('ARCH-RULES-INVALID', 'Custom rules must be an array');
+  for (const rule of rules) {
+    if (!rule || typeof rule.id !== 'string' || !rule.id || typeof rule.pattern !== 'string'
+      || typeof rule.message !== 'string' || typeof rule.blocking !== 'boolean' || !['ast', 'regex'].includes(rule.engine)) {
+      throw error('ARCH-RULES-INVALID', 'Custom rules require id, engine, pattern, message and blocking');
+    }
+    if (rule.engine === 'ast') syntaxKind(rule.pattern);
+    else {
+      if (/\\[1-9]|\(\?<|\(\?=|\(\?!/.test(rule.pattern)) throw error('ARCH-REGEX-UNSUPPORTED', 'Unsafe regex rule');
+      try { new RegExp(rule.pattern, 'gu'); } catch { throw error('ARCH-REGEX-UNSUPPORTED', 'Invalid regex rule'); }
+    }
+  }
+}
+function position(node, source) {
+  const start = node.getStart(source); const at = source.getLineAndCharacterOfPosition(start);
+  return { line: at.line + 1, column: at.character + 1, start, end: node.end, syntaxKind: ts.SyntaxKind[node.kind] };
+}
+function unwrap(node) {
+  while (node) {
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)
+      || ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node)) node = node.expression;
+    else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.CommaToken) node = node.right;
+    else break;
+  }
+  return node;
+}
+function memberName(node) {
+  node = unwrap(node);
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node)) return `${memberName(node.expression)}.${node.name.text}`;
+  if (ts.isElementAccessExpression(node) && node.argumentExpression && ts.isStringLiteralLike(node.argumentExpression)) {
+    return `${memberName(node.expression)}.${node.argumentExpression.text}`;
+  }
+  return '';
+}
+function propertyName(node) {
+  return node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : '';
+}
+function valueProperty(node) {
+  const parent = node.parent;
+  if (parent && ts.isPropertyAssignment(parent) && parent.initializer === node) return propertyName(parent.name);
+  if (parent && ts.isJsxAttribute(parent)) return parent.name.getText();
+  if (parent && ts.isJsxExpression(parent) && parent.parent && ts.isJsxAttribute(parent.parent)) return parent.parent.name.getText();
+  return '';
+}
+function builtinMatches(node) {
+  const matches = [];
+  const call = ts.isCallExpression(node); const construct = ts.isNewExpression(node);
+  const name = call || construct ? memberName(node.expression) : '';
+  if ((call && /^(?:(?:globalThis|window|global)\.)?eval$/.test(name))
+    || ((call || construct) && /^(?:(?:globalThis|window|global)\.)?Function$/.test(name))) matches.push('no-eval');
+  if (ts.isDebuggerStatement(node) || (call && /^(?:(?:globalThis|window|global)\.)?console\.(?:log|debug)$/.test(name))) matches.push('no-debug');
+  if (ts.isJsxAttribute(node) && node.name.getText() === 'style') matches.push('no-inline-style');
+  if (ts.isStringLiteralLike(node) && COLOR_PROPERTIES.has(valueProperty(node))
+    && /#[0-9a-f]{3,8}\b|\brgba?\s*\(|\bhsla?\s*\(/i.test(node.text)) matches.push('no-hardcoded-color');
+  if (ts.isNumericLiteral(node) && Number(node.text) > 1) matches.push('no-magic-number');
+  return matches;
+}
+function importedDependency(node) {
+  if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier
+    && ts.isStringLiteralLike(node.moduleSpecifier)) return node.moduleSpecifier.text;
+  if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)
+    && node.moduleReference.expression && ts.isStringLiteralLike(node.moduleReference.expression)) return node.moduleReference.expression.text;
+  if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)
+    && ts.isStringLiteralLike(node.argument.literal)) return node.argument.literal.text;
+  if (ts.isCallExpression(node) && node.arguments.length >= 1 && ts.isStringLiteralLike(node.arguments[0])
+    && (node.expression.kind === ts.SyntaxKind.ImportKeyword || memberName(node.expression) === 'require')) return node.arguments[0].text;
+  return null;
+}
+function bodyFunction(node) {
+  return ts.isFunctionLike(node) && node.body !== undefined;
+}
+function controlNode(node) {
+  return ts.isIfStatement(node) || ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)
+    || ts.isWhileStatement(node) || ts.isDoStatement(node) || ts.isSwitchStatement(node) || ts.isTryStatement(node)
+    || ts.isCatchClause(node) || ts.isWithStatement(node) || ts.isConditionalExpression(node);
+}
+function nestingIncrement(node) {
+  if (controlNode(node)) return 1;
+  if (!ts.isBlock(node)) return 0;
+  if (node.parent && (controlNode(node.parent) || ts.isCaseClause(node.parent) || ts.isDefaultClause(node.parent))) return 0;
+  return 1;
+}
+function astAnalysis(source, rules) {
+  const selected = new Map(rules.filter(rule => rule.engine === 'ast').map(rule => [rule.id, { rule, kind: syntaxKind(rule.pattern), locations: [] }]));
+  const builtin = new Map([...BUILTINS.keys()].map(id => [id, []]));
+  const dependencies = []; let maxFunctionLines = 0; let maxNestingDepth = 0; let animations = 0; let transitions = 0;
+  function visit(node, depth) {
+    const nextDepth = depth + nestingIncrement(node); maxNestingDepth = Math.max(maxNestingDepth, nextDepth);
+    if (bodyFunction(node)) {
+      const start = source.getLineAndCharacterOfPosition(node.getStart(source)).line;
+      const end = source.getLineAndCharacterOfPosition(Math.max(node.getStart(source), node.end - 1)).line;
+      maxFunctionLines = Math.max(maxFunctionLines, end - start + 1);
+    }
+    for (const selectedRule of selected.values()) if (node.kind === selectedRule.kind) selectedRule.locations.push(position(node, source));
+    for (const id of builtinMatches(node)) builtin.get(id).push(position(node, source));
+    const dependency = importedDependency(node); if (dependency) dependencies.push({ dependency, ...position(node, source) });
+    if (ts.isPropertyAssignment(node) || ts.isJsxAttribute(node)) {
+      const property = propertyName(node.name);
+      if (['animation', 'animationName'].includes(property)) animations += 1;
+      if (['transition', 'transitionProperty'].includes(property)) transitions += 1;
+    }
+    ts.forEachChild(node, child => visit(child, nextDepth));
+  }
+  visit(source, 0);
+  return { selected, builtin, dependencies, maxFunctionLines, maxNestingDepth, animations, transitions };
+}
+function manifestDependencies(file) {
+  const basename = file.path.split('/').at(-1);
+  if (basename === 'package.json') {
+    const source = ts.parseJsonText(file.path, file.content);
+    if (source.parseDiagnostics.length) throw error('ARCH-DEPENDENCY-MANIFEST-INVALID', 'Invalid package.json syntax');
+    const manifest = JSON.parse(file.content);
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw error('ARCH-DEPENDENCY-MANIFEST-INVALID', 'package.json must be an object');
+    return ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].flatMap(key => {
+      const entries = manifest[key];
+      if (entries === undefined) return [];
+      if (!entries || typeof entries !== 'object' || Array.isArray(entries)
+        || Object.values(entries).some(value => typeof value !== 'string')) throw error('ARCH-DEPENDENCY-MANIFEST-INVALID', `Invalid ${key} declarations`);
+      return Object.entries(entries).flatMap(([name, declaration]) => {
+        const alias = declaration.match(/^npm:(@[^/\s]+\/[^@\s]+|[^@\s]+)(?:@.*)?$/)?.[1];
+        return alias ? [name, alias] : [name];
+      });
+    });
+  }
+  if (/^requirements(?:[-.][^/]*)?\.txt$/i.test(basename)) return file.content.split(/\r?\n/)
+    .map(line => line.replace(/\s+#.*$/, '').trim()).filter(line => line && !line.startsWith('#') && !line.startsWith('-'))
+    .map(line => line.split(/[<>=!~\[;\s]/, 1)[0]);
+  if (basename === 'pom.xml') return [...file.content.matchAll(/<dependency\b[^>]*>[\s\S]*?<artifactId>\s*([^<\s]+)\s*<\/artifactId>[\s\S]*?<\/dependency>/g)].map(match => match[1]);
+  if (basename === 'Cargo.toml') {
+    let section = false; let dependencyTable = false;
+    return file.content.split(/\r?\n/).flatMap(raw => {
+      const line = raw.replace(/\s+#.*$/, '');
+      const heading = line.trim().match(/^\[([^\]]+)]$/);
+      if (heading) {
+        const dependency = heading[1].match(/(?:^|\.)(?:(?:dev|build)-)?dependencies(?:\.([A-Za-z0-9_-]+))?$/);
+        section = Boolean(dependency); dependencyTable = Boolean(dependency?.[1]);
+        return dependencyTable ? [dependency[1]] : [];
+      }
+      const item = section ? line.match(/^\s*([A-Za-z0-9_-]+)\s*=/)?.[1] : undefined;
+      const renamed = section && (dependencyTable || item) ? line.match(/\bpackage\s*=\s*["']([^"']+)["']/)?.[1] : undefined;
+      return [...(item && !dependencyTable ? [item] : []), ...(renamed ? [renamed] : [])];
+    });
+  }
+  return [];
+}
+const dependencyKey = value => value.toLowerCase().replace(/[._]+/g, '-');
+function dependencyMatch(actual, forbidden) {
+  return dependencyKey(actual) === dependencyKey(forbidden) || actual.startsWith(`${forbidden}/`)
+    || actual.startsWith(`${forbidden}.`)
+    || dependencyKey(actual.split(':').at(-1)) === dependencyKey(forbidden);
+}
+function dependencyFindings(contract, file, imported = []) {
+  let declared;
+  try { declared = manifestDependencies(file); } catch (cause) {
+    return [finding('ARCH-DEPENDENCY-MANIFEST-INVALID', file.path, 'Dependency manifest cannot be inspected.', 'architecture', true, { reason: cause.code ?? 'INVALID_JSON' })];
+  }
+  const forbidden = [...new Set([...(contract.stack.frontend?.forbiddenDeps ?? []), ...(contract.stack.backend?.forbiddenDeps ?? [])])];
+  return forbidden.flatMap(dependency => {
+    const locations = imported.filter(item => dependencyMatch(item.dependency, dependency));
+    const declarations = declared.filter(item => dependencyMatch(item, dependency));
+    return locations.length || declarations.length ? [finding('ARCH-FORBIDDEN-DEPENDENCY', file.path,
+      `Dependency ${dependency} is forbidden by the contract.`, 'architecture', true, { dependency, declarations, locations })] : [];
+  });
+}
+function languageFindings(contract, file) {
+  const languages = [contract.stack.frontend?.language, contract.stack.backend?.language].filter(Boolean);
+  const extensions = new Set(languages.flatMap(language => language === 'typescript' ? ['ts', 'tsx', 'mts', 'cts']
+    : language.startsWith('nodejs') ? ['js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'mts', 'cts']
+      : language === 'javascript' ? ['js', 'jsx', 'mjs', 'cjs']
+      : language.startsWith('python') ? ['py'] : language.startsWith('java') ? ['java'] : language.startsWith('rust') ? ['rs'] : []));
+  const extension = file.path.split('.').at(-1);
+  const framework = contract.stack.frontend?.framework ?? '';
+  if (framework.startsWith('vue')) extensions.add('vue');
+  if (framework.startsWith('svelte')) extensions.add('svelte');
+  if (framework.startsWith('wechat')) extensions.add('wxml');
+  return (SCRIPT_KINDS.has(extension) || archguardComponentLanguage(file.path) || ['py', 'java', 'rs', 'go', 'c', 'cpp'].includes(extension))
+    && extensions.size && !extensions.has(extension) ? [finding('ARCH-LANGUAGE', file.path,
+      `File extension .${extension} is outside the locked languages.`, 'architecture', true, { allowedExtensions: [...extensions] })] : [];
+}
+function budgetFindings(contract, metric) {
+  if (!metric.complexityChecked) return [];
+  const checks = [['maxFileLines', 'fileLines'], ['maxFunctionLines', 'maxFunctionLines'],
+    ['maxNestingDepth', 'maxNestingDepth'], ['animations', 'animations'], ['transitions', 'transitions']];
+  return checks.flatMap(([budgetKey, metricKey]) => {
+    const budget = contract.budgets[budgetKey];
+    if (!Number.isSafeInteger(budget) || budget < -1) throw error('ARCH-BUDGET-INVALID', `Invalid ${budgetKey} budget`);
+    return budget >= 0 && metric[metricKey] > budget ? [finding(`BUDGET-${budgetKey.toUpperCase()}`, metric.path,
+      `${metricKey} ${metric[metricKey]} exceeds budget ${budget}.`, 'complexity', true, { actual: metric[metricKey], budget })] : [];
+  });
+}
+function evaluatedRules(contract, file, analysis) {
+  const findings = [];
+  for (const [id, locations] of analysis.builtin) {
+    if (!locations.length) continue;
+    const [category, message] = BUILTINS.get(id);
+    const blocking = category === 'security' || contract.rules.strictStandard || contract.rules.blocking.includes(id);
+    findings.push(finding(id, file.path, message, category, blocking, { matches: locations.length, locations }));
+  }
+  for (const { rule, locations } of analysis.selected.values()) if (locations.length) {
+    findings.push(finding(rule.id, file.path, rule.message, 'custom', rule.blocking, { matches: locations.length, locations }));
+  }
+  return [...findings, ...regexFindings(contract, file)];
+}
+function regexFindings(contract, file) {
+  const findings = [];
+  for (const rule of contract.rules.custom.filter(rule => rule.engine === 'regex')) {
+    const matches = [...file.content.matchAll(new RegExp(rule.pattern, 'gu'))];
+    if (matches.length) findings.push(finding(rule.id, file.path, rule.message, 'custom', rule.blocking,
+      { matches: matches.length, offsets: matches.map(match => match.index) }));
+  }
+  return findings;
+}
+function syntaxDiagnostics(source) {
+  const fileName = source.fileName;
+  const host = { getSourceFile: name => name === fileName ? source : undefined,
+    getDefaultLibFileName: () => '', writeFile: () => {}, getCurrentDirectory: () => '',
+    getDirectories: () => [], fileExists: name => name === fileName,
+    readFile: name => name === fileName ? source.text : undefined, getCanonicalFileName: name => name,
+    useCaseSensitiveFileNames: () => true, getNewLine: () => '\n' };
+  const program = ts.createProgram([fileName], { allowJs: true, noLib: true, noResolve: true,
+    target: ts.ScriptTarget.Latest, jsx: ts.JsxEmit.Preserve }, host);
+  return program.getSyntacticDiagnostics(source);
+}
+function analyzeScriptFile(file, rules) {
+  const source = ts.createSourceFile(file.path, file.content, ts.ScriptTarget.Latest, true, SCRIPT_KINDS.get(file.path.split('.').at(-1)));
+  const diagnostics = syntaxDiagnostics(source).map(diagnostic => {
+    const at = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+    return { code: diagnostic.code, start: diagnostic.start ?? 0, end: (diagnostic.start ?? 0) + (diagnostic.length ?? 0),
+      line: at.line + 1, column: at.character + 1, message: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n') };
+  });
+  return diagnostics.length ? { diagnostics } : { ...astAnalysis(source, rules), diagnostics: [] };
+}
+function evaluateFile(contract, file) {
+  const inspectionScope = archguardInspectionScope(file.path, file.content, contract.audit);
+  const metric = { path: file.path, inspectionScope, complexityChecked: false, fileLines: file.content.split(/\r?\n/).length,
+    maxNestingDepth: 0, maxFunctionLines: 0, animations: 0, transitions: 0 };
+  if (!safePath(file.path)) return { metric, findings: [finding('ARCH-PATH', file.path, 'File path is unsafe.')] };
+  if (inspectionScope !== 'first-party') return { metric,
+    findings: inspectionScope === 'generated' ? dependencyFindings(contract, file) : [] };
+  const findings = languageFindings(contract, file);
+  if (file.path === 'arch.contract.yaml') findings.push(finding('ARCH-CONTRACT-MUTATION', file.path,
+    'The locked architecture contract cannot be changed by checkpoint.'));
+  const extension = file.path.split('.').at(-1); const scriptKind = SCRIPT_KINDS.get(extension);
+  if (archguardComponentLanguage(file.path)) {
+    const analysis = analyzeArchguardComponent(file, contract.rules.custom, analyzeScriptFile);
+    if (analysis.diagnostics.length) findings.push(finding('ARCH-AST-SYNTAX', file.path,
+      'Component contains parser errors or an uninspectable block.', 'architecture', true, { diagnostics: analysis.diagnostics }));
+    else {
+      for (const key of ['maxNestingDepth', 'maxFunctionLines', 'animations', 'transitions']) metric[key] = analysis[key];
+      metric.complexityChecked = true;
+      findings.push(...dependencyFindings(contract, file, analysis.dependencies), ...evaluatedRules(contract, file, analysis), ...budgetFindings(contract, metric));
+    }
+    return { metric, findings };
+  }
+  if (archguardNativeLanguage(file.path)) {
+    const analysis = analyzeArchguardLanguage(file, contract.rules.custom);
+    if (analysis.diagnostics.length) findings.push(finding('ARCH-AST-SYNTAX', file.path,
+      'Source contains parser errors; AST inspection is incomplete.', 'architecture', true, { diagnostics: analysis.diagnostics }));
+    else {
+      for (const key of ['maxNestingDepth', 'maxFunctionLines', 'animations', 'transitions']) metric[key] = analysis[key];
+      metric.complexityChecked = true;
+      findings.push(...dependencyFindings(contract, file, analysis.dependencies), ...evaluatedRules(contract, file, analysis), ...budgetFindings(contract, metric));
+    }
+    return { metric, findings };
+  }
+  if (scriptKind === undefined) {
+    findings.push(...dependencyFindings(contract, file), ...regexFindings(contract, file));
+    if (!nonSourceFile(file.path)) {
+      findings.push(finding('ARCH-AST-LANGUAGE-UNSUPPORTED', file.path,
+        'AST language is unsupported. Supported source: TypeScript/JavaScript, CSS/WXSS, Vue/Svelte/WXML, Python, Java and Rust.',
+        'architecture', true, { extension }));
+    } else if (!findings.some(item => item.ruleId === 'ARCH-DEPENDENCY-MANIFEST-INVALID')) metric.complexityChecked = true;
+    return { metric, findings: [...findings, ...budgetFindings(contract, metric)] };
+  }
+  const source = ts.createSourceFile(file.path, file.content, ts.ScriptTarget.Latest, true, scriptKind);
+  const diagnostics = syntaxDiagnostics(source);
+  if (diagnostics.length) {
+    findings.push(finding('ARCH-AST-SYNTAX', file.path, 'Source contains parser errors; AST inspection is incomplete.', 'architecture', true,
+      { diagnostics: diagnostics.map(diagnostic => {
+        const at = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+        return { code: diagnostic.code, line: at.line + 1, column: at.character + 1,
+          message: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n') };
+      }) }));
+    return { metric, findings };
+  }
+  const analysis = astAnalysis(source, contract.rules.custom);
+  for (const key of ['maxNestingDepth', 'maxFunctionLines', 'animations', 'transitions']) metric[key] = analysis[key];
+  metric.complexityChecked = true;
+  findings.push(...dependencyFindings(contract, file, analysis.dependencies), ...evaluatedRules(contract, file, analysis), ...budgetFindings(contract, metric));
+  return { metric, findings };
+}
+export function evaluateArchguardFiles(contract, files) {
+  if (!contract?.rules || !contract?.stack || !contract?.budgets || !Array.isArray(contract.rules.blocking)
+    || typeof contract.rules.strictStandard !== 'boolean') throw error('ARCH-CONTRACT-INVALID', 'Inspection needs a normalized architecture contract');
+  validateArchguardAstRules(contract.rules.custom);
+  if (!Array.isArray(files) || !files.length) throw error('ARCH-FILES-EMPTY', 'At least one actual file is required');
+  const paths = new Set();
+  for (const file of files) {
+    if (!file || typeof file.path !== 'string' || typeof file.content !== 'string'
+      || Object.keys(file).some(key => !['path', 'content'].includes(key)) || paths.has(file.path)) {
+      throw error('ARCH-FILE-INVALID', 'Files require a unique path and content without caller-supplied evidence');
+    }
+    paths.add(file.path);
+  }
+  const evaluated = files.map(file => evaluateFile(contract, file));
+  return { findings: evaluated.flatMap(item => item.findings), metrics: evaluated.map(item => item.metric) };
+}

package/local-archguard-checkpoint.mjs

@@ -0,0 +1,123 @@
+import { withArchguardMutationFence } from './local-archguard-mutation-fence.mjs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { verifyMutationPass } from './local-execution.mjs';
+import { context, canonical, sha256, safePath, safeId, readBytes, readJson, fail, authority,
+  verifyAuthority, withExclusiveLock, appendLedger, readLedger } from './local-archguard-state.mjs';
+import { freezeContract } from './local-archguard-contract.mjs';
+import { loadSnapshot, restoreSnapshot, MISSING_SHA256, history, drift } from './local-archguard-snapshot.mjs';
+import { evaluateArchguardCheckpoint, parseArchguardContract, evaluateArchguardDrift } from './local-archguard-evaluate.mjs';
+import { signRunnerReceipt } from './local-archguard-signing.mjs';
+
+async function verifyWriteAuthorization(ctx, input, snapshot) {
+  const savedPass = await readJson(input.gatePassPath);
+  const verified = await verifyMutationPass({ ...input, repositoryRoot: ctx.root, targetPath: input.path });
+  const pass = verified.pass;
+  if (canonical(pass) !== canonical(savedPass) || canonical(await readJson(input.gatePassPath)) !== canonical(savedPass)) fail('ARCH_PASS_RACE', 'gate pass changed during verification');
+  if (pass.snapshotId !== snapshot.snapshotId || pass.snapshotReceipt.snapshotDigest !== snapshot.snapshotDigest
+    || pass.snapshotReceipt.contractDigest !== snapshot.contractDigest || pass.stepId !== snapshot.stepId
+    || canonical(pass.paths) !== canonical([...snapshot.paths, 'arch.contract.yaml'].sort())) fail('ARCH_PASS_BINDING', 'gate pass is not bound to the exact snapshot and path set');
+  const verifiedScope = await verifyAuthority(ctx, input.scopeAuthorization, 'entrorove.archguard-scope-authorization/1.0');
+  const scope = verifiedScope.value;
+  if (scope.stepId !== snapshot.stepId || scope.snapshotDigest !== snapshot.snapshotDigest || scope.contractDigest !== snapshot.contractDigest
+    || scope.passDigest !== sha256(canonical(pass)) || canonical(scope.paths) !== canonical(snapshot.paths)
+    || !verifiedScope.authority.actors.includes(scope.ownerId) || typeof scope.leaseId !== 'string' || !scope.leaseId
+    || !Number.isSafeInteger(scope.generation) || scope.generation < 1
+    || ['taskDigest', 'chainDigest', 'scopeArtifactDigest'].some(key => !/^[0-9a-f]{64}$/.test(scope[key]))) fail('ARCH_SCOPE_AUTHORIZATION', 'signed scope authorization does not bind the accepted owner, task, chain, lease, snapshot, pass, and paths');
+  return { scope, pass };
+}
+function invalidCheckpoint(snapshot, input, afterSha256, error) {
+  const ruleId = /^[A-Z0-9_-]+$/.test(error.code ?? '') ? error.code : 'ARCH_LOCAL_EXECUTION_FAILED';
+  const finding = { severity: 'P1', ruleId, entityRef: input.path, message: `Local authorization or contract verification failed (${ruleId}).`,
+    category: 'authorization', blocking: true, evidence: error.evidence ?? {} };
+  return { checkpoint: { status: 'blocked', writeAllowed: false, rollbackRequired: true, findings: [finding],
+    metrics: { path: input.path, inspectionScope: 'first-party', complexityChecked: false, fileLines: 0,
+      maxFunctionLines: 0, maxNestingDepth: 0, animations: 0, transitions: 0 }, instruction: 'rollback-block-and-correct' },
+    ledgerEntry: { schemaVersion: 'archguard.checkpoint-ledger/1.0', checkpointId: sha256(canonical({ snapshot: snapshot.snapshotDigest, blockId: input.blockId, ruleId, afterSha256 })),
+      blockId: input.blockId, path: input.path, contractRevision: snapshot.contractRevision, beforeSha256: snapshot.files.find(file => file.path === input.path).sha256,
+      afterSha256, status: 'blocked', ruleIds: [ruleId], blockingRuleIds: [ruleId], rollbackRequired: true } };
+}
+async function checkpointReceipt(ctx, input, snapshot, result, authorization, rollback) {
+  const scope = authorization.scope; const entry = result.ledgerEntry;
+  const payload = { schemaVersion: 'entrorove.archguard-checkpoint-receipt/1.0', repositoryDigest: ctx.repositoryDigest,
+    flowId: ctx.flowId, stepId: input.stepId, ownerId: scope.ownerId,
+    leaseId: scope.leaseId, generation: scope.generation,
+    taskDigest: scope.taskDigest, chainDigest: scope.chainDigest, scopeArtifactDigest: scope.scopeArtifactDigest,
+    contractDigest: snapshot.contractDigest, contractRevision: entry.contractRevision, snapshotDigest: snapshot.snapshotDigest,
+    passDigest: sha256(canonical(authorization.pass)), path: input.path, blockId: input.blockId,
+    beforeSha256: entry.beforeSha256, afterSha256: entry.afterSha256, checkpoint: result.checkpoint, ledgerEntry: entry,
+    rollbackOutcome: rollback.restored ? 'restored' : 'retained', issuedAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 60_000).toISOString(), nonce: randomUUID(),
+    scopeAuthorizationDigest: sha256(canonical(input.scopeAuthorization)) };
+  return signRunnerReceipt(ctx, payload);
+}
+async function checkpointLocked(ctx, input) {
+  safeId(input.stepId, 'stepId'); safeId(input.blockId, 'blockId'); safePath(input.path);
+  const ledger = await readLedger(ctx); const snapshot = await loadSnapshot(ctx, input.snapshotId);
+  if (ledger.entries.some(entry => entry.event === 'checkpoint' && entry.data.snapshotId === snapshot.snapshotId)) fail('ARCH_SNAPSHOT_CONSUMED', 'snapshot checkpoint was already consumed; replay rejected');
+  if (snapshot.stepId !== input.stepId || !snapshot.paths.includes(input.path)) fail('ARCH_CHECKPOINT_SCOPE', 'checkpoint path or step is outside the snapshot scope');
+  const original = snapshot.files.find(file => file.path === input.path); let authorization; let result; let current;
+  let afterSha256 = MISSING_SHA256; let contract;
+  const contractBaseline = snapshot.files.find(file => file.path === 'arch.contract.yaml');
+  contract = await parseArchguardContract(Buffer.from(contractBaseline.content, 'base64').toString('utf8'));
+  snapshot.contractRevision = contract.revision;
+  try {
+    if (drift(ledger).interrupted) fail('ARCH_RED_INTERRUPT', 'mutation is interrupted by three consecutive blocks');
+    authorization = await verifyWriteAuthorization(ctx, input, snapshot);
+    const locked = await freezeContract(ctx);
+    if (locked.contractDigest !== snapshot.contractDigest || locked.rawDigest !== snapshot.contractRawDigest) fail('ARCH_CONTRACT_DRIFT', 'checkpoint contract differs from its original snapshot');
+    for (const expected of snapshot.files.filter(file => file.path !== input.path && file.path !== 'arch.contract.yaml')) {
+      const actual = await readBytes(path.join(ctx.root, expected.path), true, ctx);
+      const actualSha256 = actual.exists ? sha256(actual.content) : MISSING_SHA256;
+      if (actualSha256 !== expected.sha256) throw Object.assign(new Error('another source path changed without its own block checkpoint'), {
+        code: 'ARCH_UNCHECKPOINTED_PATH', evidence: { path: expected.path, beforeSha256: expected.sha256, afterSha256: actualSha256 } });
+    }
+    current = await readBytes(path.join(ctx.root, input.path), false, ctx); afterSha256 = sha256(current.content);
+    result = await evaluateArchguardCheckpoint(contract, { blockId: input.blockId, path: input.path,
+      content: current.content.toString('utf8'), beforeSha256: original.sha256 }, history(ledger));
+  } catch (error) {
+    if (!current) {
+      try { current = await readBytes(path.join(ctx.root, input.path), true, ctx); afterSha256 = current.exists ? sha256(current.content) : MISSING_SHA256; } catch { /* No unsafe file read is necessary for rollback. */ }
+    }
+    result = invalidCheckpoint(snapshot, input, afterSha256, error);
+  }
+  let status = result.checkpoint.status;
+  if (current) {
+    try {
+      const latest = await readBytes(path.join(ctx.root, input.path), true, ctx);
+      if (latest.exists !== current.exists || (latest.exists && sha256(latest.content) !== afterSha256)) {
+        afterSha256 = latest.exists ? sha256(latest.content) : MISSING_SHA256;
+        fail('ARCH_CHECKPOINT_RACE', 'source changed during checkpoint; no stale result was accepted');
+      }
+    } catch (error) { result = invalidCheckpoint(snapshot, input, afterSha256, error); status = 'blocked'; }
+  }
+  result.checkpoint.drift = await evaluateArchguardDrift([...history(ledger), result.ledgerEntry]);
+  let rollback = status === 'blocked' ? await restoreSnapshot(ctx, snapshot) : { restored: false, paths: [], reason: 'passed block retained' }; let receipt = null;
+  try { receipt = authorization ? await checkpointReceipt(ctx, input, snapshot, result, authorization, rollback) : null; }
+  catch (error) {
+    result = invalidCheckpoint(snapshot, input, afterSha256, error); status = 'blocked';
+    result.checkpoint.drift = await evaluateArchguardDrift([...history(ledger), result.ledgerEntry]);
+    if (!rollback.restored) rollback = await restoreSnapshot(ctx, snapshot);
+  }
+  let record;
+  try {
+    record = await appendLedger(ctx, 'checkpoint', { snapshotId: snapshot.snapshotId, status,
+      contractDigest: snapshot.contractDigest, ledgerEntry: result.ledgerEntry, checkpoint: result.checkpoint, rollback,
+      receiptDigest: receipt ? sha256(canonical(receipt)) : null });
+  } catch (error) {
+    if (!rollback.restored) await restoreSnapshot(ctx, snapshot);
+    fail('ARCH_CHECKPOINT_AUDIT_FAILED', `checkpoint append failed (${error.code ?? 'state error'}); block was restored and no success may be reported`);
+  }
+  return { schemaVersion: 'entrorove.archguard-checkpoint-result/1.0', ...result, status, rollback,
+    exitCode: status === 'blocked' ? 2 : 0, evidenceState: receipt ? 'signed' : 'reported', receipt,
+    processLedgerDigest: record.digest, ledgerPath: path.join(ctx.directory, 'ledger.jsonl') };
+}
+export async function archguardCheckpoint(input) {
+  return withArchguardMutationFence(input, async assertPaths => {
+    const ctx = await context(input);
+    const snapshot = await loadSnapshot(ctx, input.snapshotId);
+    await assertPaths(snapshot.paths);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), async () =>
+      withExclusiveLock(path.join(ctx.directory, 'mutation.lock'), async () => checkpointLocked(ctx, input)));
+  });
+}