code-standards 8.117.0__tar.gz → 8.121.0__tar.gz

{code_standards-8.117.0 → code_standards-8.121.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-standards
-Version: 8.117.0
+Version: 8.121.0
 Summary: One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy.
 Project-URL: Homepage, https://code-standards.sarj.ai/
 Project-URL: Documentation, https://code-standards.sarj.ai/cli/
@@ -105,7 +105,7 @@ Unused private Python test helpers require `reportUnusedFunction` set to `warnin
 
 DevOps execution blocks may sequence existing commands without helper scripts. Keep interpreter source, control flow, logical chains, pipelines and substitutions in independently linted files; Python `-m` and script paths, and jq/awk `-f` files remain supported. SARJ310 is an error, including short inline programs. Cloud Build SARJ315 checks YAML and JSON for unique IDs, ordered step dependencies, script/argv exclusivity and untrusted substitutions in shell source; pass substitutions as quoted arguments to external scripts. JSON configs are discovered in operational directories or with `cloudbuild` in their filename; JSON syntax must be strict, with unique keys and finite numbers. Files named with `cloudbuild`, and Build-shaped files under a `cloudbuild` directory, use the bundled, digest-verified Google Build v1 field schema for field names, types, enums and protobuf durations/integers. The offline schema rejects output-only fields; trigger expansion, resource access and hosted admission require the deployment environment.
 
-The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Cloud Deploy validation is a documented partial structural contract. Terraform validation and TFLint require explicit repository trust and prepared local providers; analysis never initializes or downloads them. Compose requires an exact consumer `[devops].compose_version`; its source check does not resolve environment inputs.
+The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Every selected `action.yml`/`action.yaml` uses GitHub's pinned action parser and converter offline, including composite steps, expression syntax and available contexts, runtime requirements, step IDs and action-reference forms. This uses the core Node runtime and needs no referencing workflow, consumer npm setup or security capability. Cloud Deploy validation is a documented partial structural contract. Terraform validation and TFLint require explicit repository trust and prepared local providers; analysis never initializes or downloads them. Compose requires an exact consumer `[devops].compose_version`; its source check does not resolve environment inputs. Declare `compose_projects = [["base.yaml", "overlays/production.yaml"]]` in `[devops]` to validate custom filenames and overlays in invocation order. Selecting any member checks the whole project; declared fragments are not checked independently. Undeclared conventional filenames remain standalone projects. Missing inputs and native field errors fail coverage. Source checks use Compose's partially resolved model; full consistency requires the actual deployment environment.
 
 File discovery, enabled capabilities and native validation each determine coverage. Check the selected paths and tool reports; a syntax check does not establish deployment validity.
 
@@ -114,10 +114,10 @@ File discovery, enabled capabilities and native validation each determine covera
 | Terraform `.tf`, `.tf.json` | Native validation, TFLint and applicable Sarj rules | Local providers and explicit trust required; JSON is never passed to `fmt` |
 | `.tfvars`, `.tftest.hcl` | Native Terraform formatting | Variable/test files do not select module validation or TFLint |
 | `.tfvars.json`, `.tftest.json`, other `.hcl` | Applicable Sarj rules | No native formatting; JSON semantic coverage is limited |
-| Actions workflows and composite actions | actionlint for workflows and referenced action metadata; Zizmor and shared execution checks | actionlint omits standalone metadata and composite steps; security capabilities may be disabled |
+| Actions workflows and action metadata | actionlint for workflows; pinned GitHub action parser for all `action.yml`/`action.yaml` files, including composite steps; Zizmor and shared execution checks | Offline validation covers structure and expression syntax/contexts; expression values and runtime availability require GitHub; security capabilities may be disabled |
 | Cloud Build YAML/JSON | Pinned Google Build v1 field schema, SARJ315 and shared execution checks | Schema selection uses a `cloudbuild` filename or Build-shaped source in that directory; trigger inputs and hosted admission remain external |
 | Dockerfile variants | Hadolint and executable-field checks | Image-default entrypoints are not inferred |
-| `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml` | Pinned native Compose source validation | Overlays and custom filenames need assembled native validation; embedded programs are checked by content |
+| Conventional Compose filenames and declared `compose_projects` | Pinned native Compose validation of ordered file groups | Environment interpolation/resolution stays disabled; deployment must supply its actual environment inputs |
 | Skaffold and Cloud Deploy YAML | Pinned Skaffold schema; partial Cloud Deploy structure | Generated resources need prepared validation |
 | Helm charts, Kubernetes and CRDs | Prepared Helm lint/render, kubeconform and kube-linter | Receipts must bind the rendered artifacts and local schema closure |
 | Templates, systemd units, service-specific `.conf`/`.cfg` | Text rules for recognized templates and `.conf`/`.cfg`; units are not routed | Render templates and run the service's native validator; no general semantic coverage is claimed |

{code_standards-8.117.0 → code_standards-8.121.0}/README.md

@@ -65,7 +65,7 @@ Unused private Python test helpers require `reportUnusedFunction` set to `warnin
 
 DevOps execution blocks may sequence existing commands without helper scripts. Keep interpreter source, control flow, logical chains, pipelines and substitutions in independently linted files; Python `-m` and script paths, and jq/awk `-f` files remain supported. SARJ310 is an error, including short inline programs. Cloud Build SARJ315 checks YAML and JSON for unique IDs, ordered step dependencies, script/argv exclusivity and untrusted substitutions in shell source; pass substitutions as quoted arguments to external scripts. JSON configs are discovered in operational directories or with `cloudbuild` in their filename; JSON syntax must be strict, with unique keys and finite numbers. Files named with `cloudbuild`, and Build-shaped files under a `cloudbuild` directory, use the bundled, digest-verified Google Build v1 field schema for field names, types, enums and protobuf durations/integers. The offline schema rejects output-only fields; trigger expansion, resource access and hosted admission require the deployment environment.
 
-The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Cloud Deploy validation is a documented partial structural contract. Terraform validation and TFLint require explicit repository trust and prepared local providers; analysis never initializes or downloads them. Compose requires an exact consumer `[devops].compose_version`; its source check does not resolve environment inputs.
+The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Every selected `action.yml`/`action.yaml` uses GitHub's pinned action parser and converter offline, including composite steps, expression syntax and available contexts, runtime requirements, step IDs and action-reference forms. This uses the core Node runtime and needs no referencing workflow, consumer npm setup or security capability. Cloud Deploy validation is a documented partial structural contract. Terraform validation and TFLint require explicit repository trust and prepared local providers; analysis never initializes or downloads them. Compose requires an exact consumer `[devops].compose_version`; its source check does not resolve environment inputs. Declare `compose_projects = [["base.yaml", "overlays/production.yaml"]]` in `[devops]` to validate custom filenames and overlays in invocation order. Selecting any member checks the whole project; declared fragments are not checked independently. Undeclared conventional filenames remain standalone projects. Missing inputs and native field errors fail coverage. Source checks use Compose's partially resolved model; full consistency requires the actual deployment environment.
 
 File discovery, enabled capabilities and native validation each determine coverage. Check the selected paths and tool reports; a syntax check does not establish deployment validity.
 
@@ -74,10 +74,10 @@ File discovery, enabled capabilities and native validation each determine covera
 | Terraform `.tf`, `.tf.json` | Native validation, TFLint and applicable Sarj rules | Local providers and explicit trust required; JSON is never passed to `fmt` |
 | `.tfvars`, `.tftest.hcl` | Native Terraform formatting | Variable/test files do not select module validation or TFLint |
 | `.tfvars.json`, `.tftest.json`, other `.hcl` | Applicable Sarj rules | No native formatting; JSON semantic coverage is limited |
-| Actions workflows and composite actions | actionlint for workflows and referenced action metadata; Zizmor and shared execution checks | actionlint omits standalone metadata and composite steps; security capabilities may be disabled |
+| Actions workflows and action metadata | actionlint for workflows; pinned GitHub action parser for all `action.yml`/`action.yaml` files, including composite steps; Zizmor and shared execution checks | Offline validation covers structure and expression syntax/contexts; expression values and runtime availability require GitHub; security capabilities may be disabled |
 | Cloud Build YAML/JSON | Pinned Google Build v1 field schema, SARJ315 and shared execution checks | Schema selection uses a `cloudbuild` filename or Build-shaped source in that directory; trigger inputs and hosted admission remain external |
 | Dockerfile variants | Hadolint and executable-field checks | Image-default entrypoints are not inferred |
-| `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml` | Pinned native Compose source validation | Overlays and custom filenames need assembled native validation; embedded programs are checked by content |
+| Conventional Compose filenames and declared `compose_projects` | Pinned native Compose validation of ordered file groups | Environment interpolation/resolution stays disabled; deployment must supply its actual environment inputs |
 | Skaffold and Cloud Deploy YAML | Pinned Skaffold schema; partial Cloud Deploy structure | Generated resources need prepared validation |
 | Helm charts, Kubernetes and CRDs | Prepared Helm lint/render, kubeconform and kube-linter | Receipts must bind the rendered artifacts and local schema closure |
 | Templates, systemd units, service-specific `.conf`/`.cfg` | Text rules for recognized templates and `.conf`/`.cfg`; units are not routed | Render templates and run the service's native validator; no general semantic coverage is claimed |

{code_standards-8.117.0 → code_standards-8.121.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "code-standards"
-version = "8.117.0"
+version = "8.121.0"
 description = "One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy."
 readme = "README.md"
 requires-python = ">=3.14"

code_standards-8.121.0/src/sarj_standards/configs/action-parser/LICENSE.actions

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code_standards-8.121.0/src/sarj_standards/configs/action-parser/LICENSE.cronstrue

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Brady Holt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code_standards-8.121.0/src/sarj_standards/configs/action-parser/LICENSE.yaml

@@ -0,0 +1,13 @@
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

code_standards-8.121.0/src/sarj_standards/configs/action-parser/generate.mts

@@ -0,0 +1,23 @@
+import { buildSync } from 'esbuild';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const directory = fileURLToPath(new URL('.', import.meta.url));
+const output = new URL('../action-parser.cjs', import.meta.url);
+const result = buildSync({
+  absWorkingDir: directory,
+  entryPoints: ['index.mts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'cjs',
+  minify: true,
+  legalComments: 'inline',
+  write: false,
+});
+const bytes = result.outputFiles[0]!.contents;
+if (process.argv.includes('--check')) {
+  if (!readFileSync(output).equals(bytes)) throw new Error('Run npm run build to refresh the pinned action parser bundle');
+} else {
+  writeFileSync(output, bytes);
+}

code_standards-8.121.0/src/sarj_standards/configs/action-parser/index.mts

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs';
+import { getActionSchema } from '@actions/workflow-parser/actions/index';
+import { convertToIfCondition } from '@actions/workflow-parser/model/converter/if-condition';
+import { IdBuilder } from '@actions/workflow-parser/model/converter/id-builder';
+import { TemplateContext, TemplateValidationErrors } from '@actions/workflow-parser/templates/template-context';
+import { readTemplate } from '@actions/workflow-parser/templates/template-reader';
+import { isMapping, isSequence, isString } from '@actions/workflow-parser/templates/tokens/type-guards';
+import { ExpressionToken, type TemplateToken } from '@actions/workflow-parser/templates/tokens/index';
+import { NoOperationTraceWriter } from '@actions/workflow-parser/templates/trace-writer';
+import { YamlObjectReader } from '@actions/workflow-parser/workflows/yaml-object-reader';
+
+interface Source {
+  path: string;
+  content: string;
+}
+
+// ActionManifestManager adds runtime requirements after the shared template reader.
+function validateRuntime(context: TemplateContext, root: TemplateToken): void {
+  if (!isMapping(root)) return;
+  const runs = root.find('runs');
+  if (!runs || !isMapping(runs)) {
+    context.error(root, "Action requires a 'runs' mapping");
+    return;
+  }
+  if (runs.find('plugin')) return;
+  const using = runs.find('using');
+  if (!using || !isString(using)) {
+    context.error(runs, "Action requires 'runs.using'");
+    return;
+  }
+  const runtimes = context.schema.getScalarDefinitions(context.schema.getDefinition('using'));
+  if (!runtimes.some(runtime => runtime.isMatch(using))) {
+    context.error(using, `Unsupported action runtime '${using.value}'`);
+    return;
+  }
+  let required = 'main';
+  if (using.value === 'composite') required = 'steps';
+  if (using.value === 'docker') required = 'image';
+  if (!runs.find(required)) context.error(runs, `Action runtime '${using.value}' requires '${required}'`);
+  for (const key of ['pre-if', 'post-if']) {
+    const condition = runs.find(key);
+    if (!condition || !isString(condition)) continue;
+    try {
+      ExpressionToken.validateExpression(condition.value, context.schema.getDefinition('runs-if').readerContext);
+    } catch (error) {
+      context.error(condition, error);
+    }
+  }
+  const steps = runs.find('steps');
+  if (!steps || !isSequence(steps)) return;
+  const ids = new IdBuilder();
+  for (const step of steps) {
+    if (!isMapping(step)) continue;
+    const id = step.find('id');
+    if (id && isString(id)) {
+      // The runner compares known reference names without case sensitivity.
+      const error = ids.tryAddKnownId(id.value.toLowerCase());
+      if (error) context.error(id, error);
+    }
+    const condition = step.find('if');
+    if (condition) convertToIfCondition(context, condition);
+    const uses = step.find('uses');
+    if (!uses || !isString(uses) || uses.value.startsWith('./') || uses.value.startsWith('.\\') || uses.value.startsWith('$/') || uses.value.startsWith('docker://')) continue;
+    const [repository, ref, extra] = uses.value.split('@') as [string, ...string[]];
+    if (!ref || extra !== undefined || repository.split(/[\\/]/).filter(Boolean).length < 2) {
+      context.error(uses, "Action reference requires owner/repository[/path]@ref");
+    }
+  }
+}
+
+const sources = JSON.parse(readFileSync(process.argv[2]!, 'utf8')) as Source[];
+const results = sources.map(({ path, content }) => {
+  const context = new TemplateContext(new TemplateValidationErrors(), getActionSchema(), new NoOperationTraceWriter());
+  const file = context.getFileId(path);
+  const reader = new YamlObjectReader(file, content);
+  for (const error of reader.errors) context.error(file, error.message, error.range);
+  // parseAction selects action-root-strict for public metadata. The native
+  // action-root contract matches the runner, including local actions without UI labels.
+  const value = reader.errors.length ? undefined : readTemplate(context, 'action-root', reader, file);
+  if (!context.errors.count && value) {
+    validateRuntime(context, value);
+  }
+  return {
+    path,
+    errors: context.errors.getErrors().map(error => ({
+      message: error.rawMessage,
+      line: error.range?.start.line ?? 1,
+      column: error.range?.start.column ?? 1,
+    })),
+  };
+});
+process.stdout.write(JSON.stringify(results));